Understanding the InnerSource Checklist

Chapter 4. Passive Documentation and the Need for Findability

TL;DR

• Passive documentation is crucial for mentoring and capturing tribal knowledge. The team takes a communication hit at the beginning, but the increase in velocity more than makes up for it.

• You can accelerate passive documentation by rewarding both the writers and consumers of the document.

• Passive documentation must be findable to be useable. Sometimes, this means that you will need to manually cross-tag between siloed datasets.

Passive documentation is the record of the documentation we create every day while communicating openly. It is a great way to get tribal knowledge out of silos and into a format that is archival and findable. As an added bonus, it is typically kept with the project or the code that it documents, thus it is in an easy-to-find, context-relevant location.

Creating Passive Documentation

Passive documentation consists of written information that was produced not specifically to document for the future, but to explain something in the present, as it is needed. For example, it often includes the following:

• Conversations that the Trusted Committers (TCs) have while mentoring a contributor who is learning how to integrate with her codebase

• Conversations the product owners have when they are explaining their priorities to one another, or arranging them

• The connection between a piece of the code and the project stories about the code, and the live conversations about both

At first, the most ...