Writing software documentation: an approach

Whether it is a library, a tool or a complete application, who does not want good documentation for the software you use? But having a product with up to date documentation turns out to be difficult to achieve. In this article, I want to share an approach with what I think is needed to overcome the challenges. In order to have a complete view, I start off with goals and challenges of code related documentation.

“True glory consists in doing what deserves to be written, and writing what deserves to be read.”
Pliny the Elder

Documentation goals

For a sensible documentation approach, it must be clear what the goals are. The main goal is to make future code changes possible. You can imagine this when you have found yourself in a situation with source code but without any documentation. If the code is not sufficiently self explanatory, it is very difficult to make changes because you don know which choices led to the current state. There can be many aspects that are not obvious for the reader that may have led to certain decisions. And when circumstances have changed, those decisions might even have become invalid over time.

So the main purpose of documentation is to document these decisions. In other words, it should explain why decisions were made. Future readers will turn to the documentation mostly to find out reasons why decisions where made. Different documentation types (specifications, design, interface documentation) describe decisions on different levels.

Software documentation challenges

In my experience, there are a few challenges that make it difficult to have a well-documented product. The main challenge is that developers are much more fond of writing code than documenting it. And, given the choice between improving the product or documenting it, they are inevitably apt to choose the first. So writing documentation must be as easy as possible.

The second challenge is maintaining the documentation. The product is the primary deliverable and often documentation is thought of much later. It is difficult to keep documentation up to date with the product and even more when it is already outdated for a while. Since documentation is different from the source code, documentation for new functionality is often forgotten (and the first challenge might also have something to do with that). The software does not depend on it, so it also goes largely unnoticed. As a result, documentation becomes obsolete easily.

The second challenge also makes it clear that it is not sufficient to write the definitive documentation at one time. A constant amount of effort is required to keep it up to date.

A documentation approach

In order to have up to date software documentation, the mentioned goals and challenges need to be combined into a documentation approach. Using a set of basic guidelines, it is ensures that the right documentation is written and kept up to date. I want to base this on a set of basic principles, derived from the goals and challenges.

Document just what is needed, no more. People that turn to the documents don’t normally do this for fun; instead, they are looking for certain information. They want to find that information in as little time as possible so they can apply it and continue with what they are doing. Therefore, describe tersely. I think NSubstitute is a good example: almost all usage questions are answered in just a few succinct pages with clear examples.
Store together what changes together. When making a change, your job becomes much easier when you can make all changes in one place.

These principles combined lead me to a set of documentation rules that are described in the next sections. Together, they allow to have up to date documentation and easy to maintain. There are some process rules to make sure people don’t forget to update the docs. Since there is little direct relationship between documentation and sources, only on the process level this alignment can be enforced.

Think: what information may be needed by people after me? This guides the information you need to write down somehow. It may also already provide some structure to apply to the document.
Keep the document structure simple, so that it can easily be updated. If the document structure is getting in the way, then update the structure.
For each documentation goal (specification, design, API docs, change docs etc.) set up a different document. Also have specification and design in separate documents. This leads towards simpler documents. Having a single documentation goal also helps the reader to more easily find what he is looking for.
Focus on describing the why: describe the reasons why specifications are required and what problems they must solve. When describing design, focus on the design decisions and their rationale. People do not look into the design document to find the current class structure but rather to find out why it is the way it is, and what might prevent them from safely changing it..
For design documentation: if information can directly be derived from the code, then refer to it instead of documenting it again. Work towards a clear design that can explain itself and use clear naming. That way, you don’t need to document those obvious things.
If the information is available on the internet, then refer to it instead of writing it again. For instance, there is no need to explain how some design pattern works, there are excellent pages for that. Also known bugs usually have an open bug ticket somewhere that you can link to.
Decouple documentation and source code where possible. For example, in a design document, avoid using actual function names; they render the design document outdated when someone refactors the function.
Spell checkers are not only useful for witches! It may sound obvious, and many tools have integrated spell checkers, but sometimes it amazes me what sloppy documentation is being written. If a document has many spelling errors and is generally sloppy written, then reading becomes more difficult and time consuming. Considering that the document is read much more often than it is written, taking your time to write well really pays off.
Use diagrams where applicable. A picture can say more than a thousand words (and vice versa).

Storage control

If the audience consists of developers, then it may be a good idea to store the documentation together with the source code. This can also be done if the audience consists of, for example, end users, but then it needs to be converted somehow to make it accessible. Also, the documentation needs to be published together with product releases.
Use a text format so you can see diffs. Using markdown is easy and allows for basic formatting. Many markdown renderers support diagrams like mermaid. In my experience, a simple format has the added benefit that you do not have to spend time to have a nice looking document.

Process integration

Anchor documentation update in your process, for example as part of the Definition of Done. This is essential to ensure it is not forgotten. This is also an important reason to store documents with the source code: it helps both in updating the documents and makes it much easier to verify that the documentation changes correspond to the program changes. Since the documentation cannot be interpreted by tools, a human review is the only feedback you can get.
For API documentation: document with the source code and use a tool like doxygen or javadoc. Or in Visual Studio: enable document generation. This puts the API documentation as close as possible to the documentation.
You can fail the CI build when the API documentation is not complete. This helps developers not forgetting to update the API documentation. It is no guarantee though; if a change needs a documentation update but has no changed API, it might still go unnoticed. That’s also why the review process is so important.
In case you do not like to write change logs, you can consider using conventional commits and have them generated for you.

This is my current take on getting to up to date software documentation. I have written what I know, according to my experiences. In the future however I might think differently about it.