Most technical documentation goes unread not because developers don’t value docs, but because most docs are written for the wrong audience, at the wrong level of detail, in the wrong place.
The Four Kinds of Documentation
- Tutorials — learning-oriented, for someone completely new, walking through a concrete example end to end
- How-to guides — goal-oriented, for someone who knows the basics and needs to accomplish a specific task
- Reference — information-oriented, comprehensive and precise, for someone who already knows roughly what they need and just needs the exact details (API docs are the classic example)
- Explanation — understanding-oriented, the “why” behind design decisions, for someone trying to build a mental model
A huge share of bad documentation comes from mixing these four modes in one document — a tutorial that suddenly dives into exhaustive edge-case reference material loses a beginner completely, while a reference doc padded with tutorial-style hand-holding frustrates someone who already knows the basics and just needs the specific detail.
The Test That Actually Matters
Good documentation is documentation someone actually reads and successfully uses, without pinging the author with a question the docs were supposed to answer — write it, then genuinely watch someone unfamiliar try to use it, and note every single point of confusion rather than assuming it’s clear because it makes sense to you, the author.