According to Silona Bonewald (former Director of InnerSource Commons), “Passive documentation is the record of the documentation we create every day while communicating openly.”
For example, adding a description to a Pull Request is a form of passive documentation. Adding a Jira ticket identifier to the title of a Pull Request is another form of such. Linking already existing sources of technical information, is creating passive documentation.
As the majority of software development happens remotely, the only way to share information across different people is through great documentation. Documentation can be broken up into 3 categories:
Wikis and READMEs
The most traditional approach. Wikis are usually in a CMS system, and READMEs are a standard for open-source projects.
Regardless of the format, this means having documentation in the home page of a project. This page has information about the product’s usage and code. How do I install? What dependencies do I need? How is the project scaffolded?
Also traditional, but more granular. They describe how a function or line of code works.
Tools like JS Doc have an interesting approach to automate this, this form of documentation tends to be the most precarious or null one. Writing such has a huge friction.
You are already writing code context on different company information systems. On places like GitHub, Jira, and Slack. Having different kinds of discussions on these systems that help developers contextualize themselves about a codebase.
For instance, this is how passive documentation is written on a GitHub Pull request.
It’s very important to break knowledge silos to share information in a distributed team.
A well-maintained, popular open-source repository has this well thought out. People distributed across the world, collaborating on a piece of open-source software has been working since the early 2000s, when the first distributed version control systems came out. Companies can learn a lot about the open-source community.
In the open-source community, complex pieces of software are written and maintained by hundreds of people who don’t know each other, across time zones. It works like a charm, but not in the corporate world.
The corporate world has processes, and bureaucracy. Negotiations between parts need to happen to make changes, even if they’re small. There’s red tape. Obviously, we’re talking about an organization whose goal is to generate a profit and not just value for free, but undoubtedly people want to optimize for their own benefit. They want a promotion, they want to become irreplaceable.
This old meme explains it well.
Departments (or people) start to compete internally between them, and that creates knowledge silos. They start blaming each other for bugs.
Passive documentation is the solution to this problem. If people don’t want to actively document for the public good, you can reward writing passive documentation. For example, if people don’t want to write and maintain a wiki, a README, and structured code comments; you can create a gitflow process that will reward people for writing code contexts on Pull Requests.
Generally speaking, the modern collaboration stack has various tools that reward writing passive documentation. Different systems provide different pieces of context.
Version Control Software (GitHub, Bitbucket, GitLab)
Ticketing systems (Jira, ClickUp, Notion)
Internal messaging systems (Slack, Microsoft Teams)
As a product and its codebase grow, finding its passive documentation becomes harder.
You get more units to search. More repositories, more commits, more pull requests, more tickets, and more conversation threads. Also, as time goes on labor rotates in a company. The person who wrote an important module in the codebase left, with a bunch of code context on his head.
We need better tools to prepare companies for change. Change on their codebase, on their business logic, and on their workforce.
Git blame is a useful starting point, but not enough. Git blame can give you authors and commit messages, which is useful, but we can do better than that.
At Watermelon, we’ve created a VS Code extension to help you find passive documentation with ease.