Advent of Technical Writing: Internal Code Documentation Requirements

This is the fifteenth post in the Advent of Technical Writing series, wherein I will share something I have learned from my experience as a technical writer. My experience is primarily in software technical writing, but what you read may apply to different fields, too. View all posts in the series.

One of the open source projects to which I contribute at work, supervision, has a requirement that documentation must be written on new features before a PR is merged. This primarily applies to internal contributors; we are happy to write documentation as required for people who have volunteered their time to contribute code.

What does it mean that "documentation must be written on new features"? For supervision, this means that:

1. You must have docstrings in your code that clearly define new functions and classes.
2. Docstrings for functions must contain a working minimum example of how the code could be used.
3. You add a reference in our mkdocs site to auto-generate documentation from the docstrings where appropriate.

If you are adding a bigger feature, you may need to add another page of documentation. Because the library is more mature, this is not the average case. New APIs are introduced incrementally. When they are, documentation is written.

Another project to which I contribute, Inference, is also working toward making documentation as a "requirement for shipping." That is to say that you should have documentation for the feature you have written. At minimum, you need to write documentation that says how to use what you have written. The documentation doesn't need to be long, but it does need to be comprehensive. Alternatively, an engineer can write a few notes or record a Loom video (a screencast) and I can turn it into full documentation.

You may be wondering: how do I get engineers on my team to sign up for documentation as a requirement for merging PRs? Will it slow my team down? The answer to that? It will take some time to write documentation, but in the long run, you will save time. This is also the case with PR reviews. It takes some time to review PRs but by having a robust PR review practice in place you can mitigate bugs and help engineers learn about a codebase and grow their skills.

I suggest keeping documentation requirements minimal; (accurate) docs are better than no docs, even if the docs may need work later. Don't expect perfection. You can always refine documentation over time.

To get buy in from your organization, here are some points you could share about why writing documentation before pushing (or around the launch of) new features is useful:

1. Your marketing team has more information that they can use to promote your software (this is particularly important if you are writing open source software and growth of said software is part of your business).
2. Your sales team knows exactly where to point customers and prospects who have questions about a new offering.
3. Customers will have a more pleasant experience using and integrating with your feature.
4. Internal team members working with the project should not have to ask as many questions getting started, saving time for the engineers who would likely answer those questions.
5. New team members working on the project will have more context about its main parts.

For example, you could start by saying that all new Python functions require docstrings in PRs and those docstrings be referenced in your main documentation. You could say that large features that are important to your customers should have their own tutorial, but this could be co-written with a technical writer if required.

Even if documentation is not a requirement for shipping features, your actively encouraging people to write documentation will go a long way to helping create a culture where more people document code. It might be the case that your mentioning documentation a few times causes it to come up in sprint planning, with tickets or notes left on the board about important product features that need documentation.