How to create useful documentation – only write the table of content

This article is a follow-up to my post on lean documentation that I published some time ago.

In summary, lean documentation is characterized by being easy to consume and simple to keep updated. 

The purpose of lean documentation is to help you, as the reader, find answers to your questions, not to hold the detailed answers themselves. This is especially true when it comes to documentation of IT systems and code. The code itself should be the detailed answer to your questions. The documentation should only help you find where to find the answer. 

An analogy could be that the code is a book’s content and that good documentation is the table of contents (TOC) of the book, not a summary. The TOC is short, quick to read, and less frequently changed than the book’s text. It’s usually also hierarchical (parts, chapters, sections) to make searching even quicker.

Let’s look at some documentation anti-patterns.
If you don’t know what anti-patterns means, please check Wikipedia.

Anti-pattern #1 – no documentation

No documentation is the most common anti-pattern that is present in a lot of organizations. Often this happens because they don’t read part of the Agile Manifesto that says, “there is value in the items on the right.” 

A close cousin to “no documentation” is the pattern of “document wherever you like.” With the book’s analogy, no documentation means you need to read and remember the whole book to know where to look to find the answer to your questions. The consequences of this antipattern are that it takes a long time for people to get up and running, and they become very limited in how much of the system they feel comfortable operating. This causes silos, component teams, sub-optimization, difficulties to scale up, and continuously increased maintenance costs.

Anti-pattern #2 – detailed documentation

To overcome anti-pattern #1, some organizations believe that detailed documentation is the answer. According to the analogy with the book, this is like writing a summary of the book. The problem is that it takes a lot of discipline to keep the summary updated as the book’s content is continuously updated. And as soon it’s not updated, it can’t be trusted, which means the situation is the same as for anti-pattern #1.

Anti-pattern #3 – requirements as documentation

This is a strange type of documentation, but some organizations keep detailed information about feature requests as documentation. The problem is that these requirements are just deltas, the difference between one state of the system in history and the next coming state. To understand the current state, you need to build the whole chain of deltas and understand which deltas override an older change. If one link in the chain is lost, the documentation is not to be trusted. This is probably worse than no documentation since it only confuses the reader.

In the next article, I will give an example of how you can write effective documentation.

Thanks to Lisa Cowell for your help with this article