What is passive code documentation? Why is it hard to scale? What to do about it?

This blog post was originally posted here

TLDR

• Passive code documentation is crucial for capturing code context that your devs have in their head
• We have systems that reward writing passive documentation, such as GitHub and Jira
• But, we have needs for better findability of passive documentation as a product and a codebase grows
• We created a VS Code extension to tackle this problem

What is passive code documentation?

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?‍

Code comments

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.‍

Passive Documentation

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.‍

A code contributor reports something that needs to be changed

He or someone else sends a Pull Request. This contains a detailed description of the change, as well as file diffs.

Someone else reviews the PR. Detects an error, requests a change, or simply approves. There’s now a discussion thread that gives code context to other developers.
‍

Passive Documentation is crucial for capturing code context that your devs have in their head

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.

Famous meme depicting Microsoft’s organizational structure before Satya Nadella
‍

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.

We have systems that reward writing passive documentation
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)

• File diffs
• Technical motivations for a change
• Technical discussions around a change‍

Ticketing systems (Jira, ClickUp, Notion)

• Mockups with breaking and desired behavior
• Business logic motivations for a change
• Business logic discussions around a change‍

Internal messaging systems (Slack, Microsoft Teams)

• Code snippets
• Unstructured discussions around those snippets. Both on technical aspects and business logic
• Screenshots that don’t make it to version control or ticketing systems (eg: the debugging process).‍

We have needs for better findability of passive documentation
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.