The eight rules of good documentation

Imagine for a moment two common scenarios in the life of a web developer.

In the first scenario, meet Harlow. Today is Harlow’s first day on a new project. The team has a well-established codebase, a great working environment, and a robust test suite. As Harlow sits down at her desk, she’s excited to get up to speed with the team. After the morning stand-up meeting she’s pointed to the project’s documentation for installation with a slight grimace from her colleague Riley. He mentions that the docs “might be a little out of date, but should hopefully be enough to get you going.” Harlow then spends the rest of the day following the documentation until she gets stuck, at which point she is forced to dig through code or ask colleagues for guidance. What might have taken a few minutes becomes a day-long exercise in frustration, tampering Harlow’s initial excitement.

In the second scenario, meet Harrison. He’s working on a web app and finds a library that, at first glance, seems incredibly useful for his project. As he attempts to integrate it with his codebase he discovers that parts of the API seem to be glossed over in the documentation or even undocumented. In the end, he walks away from the project in favor of another solution.

Though these scenarios may be slightly exaggerated, I’m reasonably certain that many of us can relate. These problems were not primarily caused by low-quality code, but rather by poor documentation.

If useful documentation is so important to the success of projects and developer well-being, why don’t all projects have it? The answer, I believe, is that like good code, good documentation is difficult and time consuming to write.

In my eyes, there are eight rules that we can follow to produce good documentation:

1. Write documentation that is inviting and clear
2. Write documentation that is comprehensive, detailing all aspects of the project
3. Write documentation that is skimmable
4. Write documentation that offers examples of how to use the software
5. Write documentation that has repetition, when useful
6. Write documentation that is up-to-date
7. Write documentation that is easy to contribute to
8. Write documentation that is easy to find

The most important rule of good documentation is for it to be as inviting as possible. This means that we should aim to write it in the clearest terms possible without skipping over any steps. We should avoid making assumptions about what our users may know. Sometimes this can seem to be overkill, and we may be tempted to say something like “every X developer knows about Y,” but we each bring our own background and set of experiences to a project. Though this may result in more verbose documentation, it is ultimately simpler, as there is less guesswork involved for developers with all levels of experience.

Documentation should aim to be comprehensive. This means that all aspects of the project are documented. Undocumented features or exceptions can lead to frustration and become a time suck as users and other developers are forced to read through code to find the answers they need. Fully documenting all features takes away this kind of ambiguity.

When we write documentation that is skimmable, we help users find the content they need quickly. Making documentation skimmable can be accomplished by using clear headings, bulleted lists, and links. For large project documentation, a table of contents or clear navigation will help users to skip straight to what they need, rather than scrolling through a single long document.

Documentation that features examples allows users to see how they might use the code themselves. Aim to provide examples of the most common use cases for the project, while letting the comprehensive documentation detail every possibility.

It is perfectly acceptable to include some repetition in documentation, which the Write the Docs project terms “ARID” (accepts (some) repetition in documentation). Doing so acknowledges that users may not read the full docs or that some information is relevant in multiple places in the documentation. While good code may be DRY, good writing aims to be clear, and sometimes this means repeating ourselves. The Write the Docs project calls out the difference between writing that is ARID, DRY, and WET in this way:

The pursuit of minimizing repetition remains valiant! ARID does not mean WET, hence the word choice. It means: try to keep things as DRY as possible, but also recognize that you’ll inevitably need some amount of “moisture” to produce documentation.

Effective documentation is kept up-to-date. This is surprisingly challenging. We may begin our project with the best of intentions and great documentation, but as our software evolves and we are quickly iterating, it can be easy to fall out of step. If you are working as part of an agile development team, I recommend adding documentation to your team’s “definition of done.” For independent projects, try to treat documentation as an important final step.

Documentation that is easy to contribute to is also easy to keep up-to-date. The simplest way to make documentation easy to contribute to is to treat it as code, storing it as text in source control. The site and book Docs Like Code advocates for treating our docs like our code by using source control, automating builds, and applying software development tools and techniques to our documentation practices.

Documentation is only as helpful as it is easy to find. Keeping an updated README file and linking to more extensive documentation at the top of the README when necessary helps to keep discoverability simple.

I hope these guidelines are useful as you draft your project’s documentation. Sometimes it is helpful to remember that documentation isn’t just for other developers, but often for our future selves as well. When we return to a project after a number of months, we will appreciate the work we put into clear and up-to-date documentation.