New patterns: What to write, what to link, and what to skip?

[spier]

When discussing ideas for potential new InnerSource Patterns¹, we sometimes wonder which material to write ourselves, what external 3rd party material to link to, and what to skip (i.e. patterns we don't want to write at all).

Now how do we make this judgement call? I am not aware of any documentation around this. Therefore I am starting this conversation to collect input about it. If the conversations leads to conclusive answers that are easy enough to follow, we may convert this into written documentation elsewhere.

Btw I assume that this problem is generally applicable throughout the InnerSource Commons, and not strictly limited to our Patterns.

This is certainly a discussion on a meta level, so probably at risk of leading nowhere in any reasonable amount of time :) However I hope that exploring it a bit can help us to understand better how other people in the Commons are thinking about this space.

Conversation starter

We define InnerSource as:

the use of open source best practices for software development within the confines of an organization.

So when producing material for the InnerSource Commons (e.g. a Pattern), I see two approaches on the extremes:

1. saying "just do what they do in open source" and possibly linking to a resource outside of the Commons
2. repeating everything that is already documented elsewhere

As in so many cases, the extremes are often not that helpful :)

Some assumptions that I make about the audience consuming the material produced by the Commons:

• the reader may not have much hands-on experience with open source (i.e. the details of how an open source project works on the inside are unknown)
• even if they known the open source mechanics a bit better, they may need help with translating those concepts into the company-internal context

Now what do we do with this? What should be our mindset when producing material in the Commons?

Questions that we could ask ourselves, when trying to explain a given InnerSource concept:

• which documentation about this concept exists in other domains?
• which of that material can we link to (e.g. in open source), preferably freely link to (i.e. the material is not behind a paywall)
• does the documentation about this concept from other domains need "translation"? i.e. are there key differences in how this is applied in InnerSource? is it worthwhile to point out these differences in writing?
• is the concept we are explaining strictly tied to InnerSource, or is it just "good engineering practices"? in other words what is the dividing line between what is InnerSource and what is not?

As you can tell, these are unfinished thoughts. Looking forward to the conversation.

Footnotes

1. See this example of such a conversation. ↩

[rrrutledge]

This point is a good one to bring up, @spier. I've thought about this in the past and areas where InnerSource overlaps with other areas that have established literature and patterns. Here is a diagram:

Here are my favorite resources for each area:

• InnerSource Patterns
• Open Source Guide
• Fearless Change Patterns
• Art of Community

You bring up a 5th area, which is good engineering practices. The overlapping diagram is going to get complicated!

I think that when producing some new content for InnerSource it behooves us to stop and think about any likely overlap with other areas that may already have established, great content. After reviewing, then decide to link to it, copy it, translate it, reference it, or keep it as background and write something completely new. Maybe there could be a decision tree process for deciding what to do based on what you find.