Writing Documentation People Actually Read
By Mykhailo Boichuk · Co-founder & Vice-President
In short
Documentation goes unread when it is written for the author rather than the reader: comprehensive but unfocused, accurate at first but soon stale, and organized by the system’s structure rather than the reader’s questions. Docs people actually read answer specific questions, are kept current, and are organized around what the reader is trying to do.
Most documentation fails its reader
A great deal of documentation is written and then ignored, and the reasons are consistent. It is often written from the author’s point of view, describing the system as the author understands it, rather than from the reader’s point of view, answering the questions the reader actually has. It is comprehensive in a way that buries the one thing a reader needs under everything they do not.
The reader of documentation almost always arrives with a specific question or task. They are not reading for pleasure or completeness; they want an answer and they want it quickly. Documentation that does not respect this is documentation that gets abandoned in favor of asking a person or guessing.
Write to answer questions
The most useful reorientation is to organize documentation around the reader’s questions and tasks rather than the system’s internal structure. A reader looking for how to accomplish something should find a section named for that goal, not have to reverse-engineer it from a description of components.
- Organize by what the reader is trying to do, not by how the system is built.
- Put the answer near the top of each section, before the background and caveats.
- Use clear, descriptive headings so a reader can scan to the right place quickly.
Stale documentation is worse than none
Documentation that is out of date does active harm, because a reader who trusts it is led astray, and trust once broken is not easily restored. A reader who finds that the docs no longer match the software stops believing the docs entirely, which wastes all the effort that went into them.
Respect the reader’s time
Good documentation is economical. It says what the reader needs as briefly as it can, uses concrete examples because examples are often the fastest way to understand, and does not make the reader wade through prose to extract a fact. Different readers also need different things, a quick reference, a step-by-step guide, an explanation of how something works, and conflating them serves none of them well.
The practical test is whether a reader with a real question can find the answer quickly and trust it when they do. Documentation written to answer questions, kept current alongside the code, and organized for scanning meets that test. Documentation written to be comprehensive, maintained as an afterthought, and organized by the system’s architecture usually does not, no matter how much of it there is.
Key takeaways
- Documentation fails when written from the author’s view rather than the reader’s.
- Readers arrive with a specific question or task and want a quick, trustworthy answer.
- Organize docs around the reader’s goals, with the answer near the top and clear headings.
- Stale documentation is more harmful than none, because it misleads readers who trust it.
- Keep docs close to what they describe and update them as part of changing it.
Frequently asked questions
- Why does so much documentation go unread?
- Because it is written from the author’s perspective, organized by the system’s structure rather than the reader’s questions, and often comprehensive in a way that buries the one answer a reader needs.
- How should documentation be organized?
- Around what the reader is trying to do, with the answer near the top of each section and clear, descriptive headings so a reader can scan quickly to the right place.
- Is out-of-date documentation better than none?
- No. Stale documentation that readers trust actively misleads them and destroys their faith in the docs, so keeping documentation current is essential to its value.
About the author
Mykhailo Boichuk
Co-founder & Vice-President
Mykhailo is an engineer who builds native applications and the systems behind them. He concentrates on macOS and iOS performance, local-first data architecture, and the synchronization problems that come with offline-capable software.