Reader text

[rrrutledge]

This PR encompasses the proposed reader text of this Oriole.

If you want to actually see how this content looks in an Oriole, then follow these instructions for running the Oriole locally.

View sample Orioles here to see what the format is like on other, finished products.

[rrrutledge]

Some terms that I am trying to use intentionally and consistently. Every time the concept is mentioned it should be done with these chosen words.

• InnerSource
• Producer / Producing team
• Consumer / Consuming team
• Feature request / Requested feature

[rrrutledge]

Some feedback from a group review session:

• The word "value" is only used here once. Is there any more clarity that you can give to the value of inner sourcing?
• Another benefit of inner sourcing is that it will lead to a project that is easier to consume.
• What is the estimated cost to the host team (in terms of trusted committer and product owner time) to participate in inner source in this manner?
• Need to have the example situation be more specific. Still needs to be kept generic enough so that it is broadly-applicable, though. One suggestion: A client team needs a field added to an API response.

[rrrutledge]

In the text above this introduction of HOST and GUEST, you talk about the "consuming team" quite a lot. Might be good to map that to this section

Added a sentence to try to make that associated more explicit.

[rrrutledge]

Here is a PDF of the current text so that you don't have to run the Docker container in order to read it.

[mrsanz]

I really want to highlight how these are negatives, so I think that listing the disadvantages last makes sense to do that.

So in fact you don't do this for all of these scenarios. (The Workaround section doesn't do this) Here is a suggestion of one that pretty much follows the format already.

• a section outlining the "What" or Feature (also setting up the scenario).

The first scenario I'm calling the Wait it out scenario. In this option, the consuming team requests a new feature and that feature for whatever reason is not picked up by the producing team. The consuming team does nothing and limps along without the requested functionality, forced to Wait it out.

• a section outlining "how" it plays out. Highlighting Advantages and Disadvantages:

Sometimes, waiting for a solution to become more mature can make sense. This might be fine if there isn't an urgency associated with a feature request or if the benefit of the feature request is a small one. In these cases, Wait it out might be just fine.

• finally a section outlining "why" this occurs. Driving point home. In the scenario where there are Disadvantages, then Drawbacks can be highlighted instead of benefits.

Waiting may also come with real amounts of pain for the consuming team, especially if the requested functionally is never delivered. Be aware though that this can cost the company or individuals in ways that may not be obvious, affecting developer happiness or extra overhead for costs.

[rrrutledge]

Use the pattern of Features Advantages(Disadvantages), Benefits

We like: Definition, Advantages/Disadvantages, Drawbacks for each of the antipatterns. We like: Definition, Advantages, Benefits for the inner source section.

[rrrutledge]

Addressed all feedback. Here is a PDF view of the content if that's easier to review.