Technical Documentation That People Actually Read

In 1997 our team maintained a documentation directory on the file server with 47 documents. I checked the access logs. In a typical month, six of them were opened. The other forty-one had not been read since the day they were written.

This is the normal state of software documentation. It is written to satisfy a process requirement — "we need design docs" — not to answer the questions that people actually have. Here is what separates documentation that gets used from documentation that accumulates.

Start with the Reader's Question

Every piece of documentation should start with a specific question that a specific reader will have. Not "document the NMS architecture" but "explain to a new developer joining the team how data flows from a device poll to an alert being raised."

The question determines:

What to include (everything that answers it)
What to exclude (everything that does not)
The appropriate level of detail (enough to answer the question, no more)
The correct format (depends on whether the reader is learning, troubleshooting, or deciding)

Documentation without a clear reader question includes everything the author knows, which is too much, in the order the author learnt it, which is the wrong order.

The Four Types of Technical Documentation

Different reader questions require different document types. Treating them as one category produces documents that do neither job well.

Tutorials — learning-oriented. The reader wants to go from zero to working for the first time. Structure as a sequence of steps with a clear outcome at the end. Explain just enough to complete each step; do not explain the theory until the reader has something working.

How-to guides — task-oriented. The reader knows what they want to do and needs specific instructions. "How do I add a new device type?" Assume they know the system; give them the steps without the background.

Reference — information-oriented. The reader needs to look up a specific fact: what does this configuration parameter do, what are the valid values for this field. Format for scanning, not reading. Tables and lists over prose.

Explanations — understanding-oriented. The reader wants to know why, not how. Why is the data model structured this way? What were the trade-offs? This is the documentation most teams skip. It is also the documentation most useful for maintaining a system years later.

Writing for Scanning, Not Reading

Technical documentation is not read linearly. Readers scan headings to find what they need, read that section, and stop. Write accordingly:

Headings that answer questions, not label topics. "How device polling works" beats "Device Polling."
The answer first, the explanation second. Start each section with the conclusion.
Short paragraphs. A paragraph over five sentences is difficult to scan.
Code examples for anything that can be demonstrated. A ten-line example is clearer than two paragraphs describing the same thing.

Keeping Documentation Current

Documentation goes stale the moment the system changes and nobody updates the docs. The strategies that worked:

Documentation lives next to the code. In the same repository, in the same directory as the code it documents. When you change the code, you see the documentation. This is not sufficient on its own but it is necessary.

Documentation has owners. Every document has an owner who is responsible for keeping it current. Without ownership, updates are everyone's responsibility, which means nobody's.

Good documentation takes less time than bad documentation. Teams resist writing docs because they believe it takes time away from delivery. The truth is that unclear documentation — which requires you to explain the same thing repeatedly, or to debug problems that the documentation would have prevented — takes more time than writing it would have.

The Highest-Value Document You Can Write

For any non-trivial system: the runbook. A document that answers: what does this system do, how do you know it is healthy, what do you do when it is not?

In production at 2am, nobody reads architecture documents. They read the runbook. If the runbook is current and accurate, incidents resolve faster. If it is absent or stale, the engineer on call is solving the incident and reconstructing documentation simultaneously.

Write the runbook before you need it.