Pattern idea: InnerSource Site / InnerSource Handbook

[spier]

Summarizing from a slack conversation:

We have a pattern for an innersource portal, but no pattern for a developer portal to layer on top of it to act as a source of truth for all things innersource and developer at orgs.

By having information in one place with the innersource portal it drives more traffic to the innersource portal. So adding policies, templates, documentation, an events calendar, community information, etc to a website with an innersource portal being a page on that website instead of a stand alone item.

Summary/Essence of the pattern:

Have a thing that points to all your InnerSource things :)

Brainstorming names and alises for this pattern:

• InnerSource Site
• InnerSource Handbook
• InnerSource Landing page
• Source of Truth

Open online examples of implementations of this pattern

• https://innersource.flutter.com
• https://devguide.trimble.com/innersource/introduction/

[spier]

@robtuley we need your help on this one :)

[robtuley]

Hiya!

Yes this is what we're trying to do with the Flutter inner source site but there are a few odd driving forces there and I feel like due to org setup we've almost done it the wrong way round. i.e. a group level innersource team exists here at Flutter, but no 'developer experience'/developer platform type team. So our innersource team kind of end up doing both.

This makes me wonder...

• Is this useful as a different pattern from the well estabilished Innersource Portal one? I get that the angle is slightly different but my first immediate thought is that this is simply an variation/extension of the existing innersource portal pattern rather than a new pattern. i.e. it would be useful to add some notes to that existing pattern to explain how such a concept can be extended.
• For example coming at that 2nd quoted paragraph from the other direction... Most orgs have some sort of "Developer Portal" even if that is simply a wiki somewhere with no editorial guidance. The inner source portal will get more visibility and traffic if it is co-located with the existing developer portal.
• Is a 'developer portal' actually an innersource pattern? It's definitely an engineering practice pattern, but it feels like we already reflect the innersource variant.

[dellagustin-sap]

Is a 'developer portal' actually an innersource pattern? It's definitely an engineering practice pattern, but it feels like we already reflect the innersource variant.

This is a general comment, not only about this pattern, could fork into a discussion of its own:

I've given some thought already on how to leverage things that are not only InnerSource, but are InnerSource catalysts or preconditions to good InnerSource. A lot of things about InnerSource ar not purely InnerSource (as we borrow a lot of best practices from Open Source and engineering as a whole), but it would still be interesting to represent this borrowed things as InnerSource practices.

Examples here are:

• High level of test automation - just good software engineering, but creates a safety net for receiving contribution from people that are not as experience with the topics they are contributing to, lower the effort required on manual testing and review
• Good project and processes documentation - a good practice in general, ensures easy onboarding of new members and makes a project ready to scale when given human resources - also helps accepting contributions in a more "self-service" way

The list could go on, but what I mean here is, InnerSource is not only about inventing new things, but repurpose/reuse what is there and I see the InnerSource Patterns as a place to aggregate all that in a structured way - If we have to borrow and reuse, even better, we don't have to reinvent, but it should be represented in the context of InnerSource.

Would be glad to hear/read the thoughts on that.

[NewMexicoKid]

From an InnerSource community perspective (and also from a patterns community perspective), my view is that whatever helps the InnerSource practitioner succeed should be represented, either by commenting/amending existing patterns or by adapting patterns from other communities as separate InnerSource patterns. Whether something is documented as a comment (e.g., in the Resulting Context section) or as a standalone pattern should depend on what is needed. I.e., if it has its own problem, context, forces, and solution, then a standalone pattern would likely be useful. My $0.02.

[spier]

@dellagustin-sap thanks for sharing this angle. I had similar thoughts a couple of times, and cannot say that I have found a 100% satisfying answer for myself.

It has helped me to compare InnerSource to Agile/Lean.

People hearing about either of these for the first time might say "oh look, I just have to follow these prescribed steps and everything will be better". Unfortunately that doesn't work.

Instead it is rather that both of them represent a new mindset and require a major mental shift in the way that an org/team/individual looks at the way that they work.

However both of them only can release their full potential if you look at literally all aspects of "how you work" and re-evaluate them against that new mindset.

That is why sometimes one get's this strange notion of "wait, you are saying we should InnerSource-ify that element of software development as well?" But it isn't really that. It is more that every element of the software development process has the potential to be made more collaborative, more transparent/open, more inviting for contributions from "outside" of the maintainer team.

So the patterns that are describing these approaches are often not net-new. I even argue that none of them is new! Some are borrowed from other places, and applied to Engineering. Some are existing Engineering techniques but with some additional elements that create more room for the teams to unblock themselves.

To go back to @robtuley's original point:

Is a 'developer portal' actually an innersource pattern? It's definitely an engineering practice pattern, but it feels like we already reflect the innersource variant.

Yes, many of the InnerSource Patterns are existing Engineering Practice Pattern.
However they are modified to emphasize the importance of collaboration over the importance of ownership.

Also, do we truly know how well accepted the Engineering Practice Pattern themselves are?
If the ISC can help by codifying them in a structured form, and through that help the industry to mature, wouldn't that be a win for everybody?

After writing all of this I am not sure if I even wrote a sensible answer to @dellagustin-sap :) But still I will leave this here as it represents my (still confused) state of mind about this topic :)

If we want to go even deeper into this topic, I would opt for Slack, to get more of the ISC old-timers involved?

[spier]

Hi @matthew-dexter-trimble, I hope you don't mind the direct approach here.

For context

I noticed your name mentioned here in the Trimble Developer Guidelines related to InnerSource:
https://devguide.trimble.com/innersource/publish-documentation/

Here in this repo we are collecting patterns related to InnerSource. The most mature patterns get published in an online book at
https://patterns.innersourcecommons.org

My question

In this issue here we were brainstorming whether having a "central source of truth for all things InnerSource" would be a worthwhile pattern that we should document.

I was wondering if you would be interested in contributing to that, or could possibly even point me to further people involved with creating your devguide at Trimble?