Virtuous cycle between InnerSource ↔️ Documentation?

[spier]

We had a conversation in our Slack about the interplay of InnerSource ↔️ Documentation the other day.

Couple of things we were wondering about:

• Is there possibly a virtuous cycle between InnerSource and documentation?
• Which type of documentation is most relevant for InnerSource? e.g. there is Standard Base Documentation (README.md/CONTRIBUTING.md) but is there other documentation that impacts InnerSource (or is impacted by InnerSource)?
• Do we have other material here in the Commons that specifically talks about documentation in an InnerSource project?

Are there any people here with experience related to documentation? e.g. technical writers and similar roles?

Would be great to learn from you!

Looking forward to the conversation :)

[spier]

To explore this topic, it may help to answer this question first:

What is documentation?

The DIVIO Documentation System provides some interesting thoughts on this.

1. There isn’t one thing called documentation, there are four: tutorials, how-to guides, technical reference and explanation.
2. They represent four different purposes or functions, and require four different approaches to their creation. Understanding the implications of this will help improve most documentation.

Some questions that we could explore:

• Which of these types has touch points with InnerSource?
• In which of these quadrants does the Standard Base Documentation fall?
• Does a project write different documentation for users, contributors, and (eventually) trusted committers of their project?

[spier]

See information by the GitHub Docs Team about their documentation philosophy, for example:

• what to document and how to document it
• write content to be translated
• when and how to use videos (and how to create them)

[loujaybee]

We discussed this also in Slack. Persisting here. Visibility and metadata - There is a connection between documentation and metadata for general discovery. The first challenge is finding inner source, and knowing why it's valuable to you or relevant, that's a metadata problem IMO. Packages are too buried, the READMEs are often inconsistent. If you attach metadata to your packages, you can centrally expose them and drive adoption. We documented the DAZN metadata file here. That allowed us to create our inner source marketplace. I will attach a screenshot of our inner source marketplace. Metadata on the repo allowed us to allow searching tools by: language, type of package (cli, ci plugin, etc), greatly improving the first challenge of discovery. Then... you can solve the more specific challenge of documentation. Some examples of the metadata from our JSON schema:

1. Maintainers - Emails, so you can ask questions, connect, manage ownership of the package.
2. Distribution method - e.g. "Drone Plugin", "NPM", "Go Module", "Browser Extension"... etc.
3. Directory - For inner source that is buried in a mono-repo.
4. Labels - Unstructured labels to help discoverability.
5. RFCs - We had a strong RFC culture, some packages helped meet some RFC or standard.