There's a familiar irony in software: a team spends weeks writing thorough documentation, and developers ignore it — pasting error messages into search engines or reading the source code instead. The docs were complete. They just weren't usable. And those are very different things.
Documentation developers actually read is built around how developers actually work, not around exhaustively describing every feature. Here's how to write it.
Developers read documentation that helps them accomplish a task fast — not documentation that's merely complete.
What makes docs usable:
Completeness is not usefulness. Optimize for the developer getting unstuck, fast.
The trap is equating completeness with quality. A team documents every endpoint, every parameter, every option — exhaustively, accurately — and assumes that makes great docs. But a developer doesn't arrive wanting to read your complete reference; they arrive with a specific task and a specific problem, wanting to solve it and move on.
Complete-but-unusable docs force the developer to do the work of finding the relevant 2% buried in the comprehensive 100%. That's effort, and developers route around effort — to the source code, to a search engine, to anywhere they can get unstuck faster. The docs failed not because they were wrong or incomplete, but because they were organized for describing the system rather than for helping someone use it. Usefulness, not completeness, is the actual goal.
The single biggest improvement is organizing docs around what developers want to do rather than around your system's internal structure:
| Structure-oriented (weak) | Task-oriented (strong) |
|---|---|
| "The Auth Module" | "How to authenticate a user" |
| "Endpoint reference" | "How to send your first request" |
| "Configuration options" | "How to set up X for production" |
Developers think in tasks — "how do I do X?" — not in your architecture's modules. When docs are organized by task, the developer finds their goal directly and gets a path to accomplish it. When docs are organized by your internal structure, the developer has to first understand your system well enough to know where their task lives. Task-oriented docs meet developers where they are; structure-oriented docs make them come to you. This is the same task-completion lens that good engineering uses everywhere: optimize for the outcome the user wants.
Developers trust code more than prose, and for good reason — code is unambiguous and immediately actionable. A working, copy-pasteable example that a developer can drop in and run teaches more, faster, than paragraphs describing how something works.
The best docs lead with examples: here's the code that does the common thing, runnable as-is. Prose explains the why and the edges, but the example carries the how. Crucially, the examples must actually work — nothing destroys trust in documentation faster than a code sample that errors when pasted in. A developer who hits one broken example assumes the rest of the docs are unreliable too and goes back to the source code. Runnable, correct, copy-pasteable examples are the backbone of docs developers actually use.
Finally, usable docs are honest about the unhappy paths. The happy path is the easy part to document and the least valuable, because developers mostly reach for docs when something isn't working — an error, an edge case, an unexpected behavior. Docs that only cover the happy path abandon developers at exactly the moment they need help most.
This mirrors why agents fail in production: the happy path is the easy 80%; the unhappy paths are where the real value (and the real difficulty) live. Docs that handle the hard parts are the ones developers come to rely on.
Q: Isn't complete documentation always better? Complete and useful aren't the same thing. Exhaustive docs organized around your system's structure can still be useless if developers can't quickly find and accomplish their task. Completeness is a feature only when it's paired with task-oriented organization, runnable examples, and scannability. Optimize for the developer getting unstuck fast — completeness in service of that, not for its own sake.
Q: Why do developers prefer reading source code over docs? Usually because the source code gets them unstuck faster than the docs do — which is a docs failure, not a developer quirk. If docs were task-oriented, full of working examples, and honest about errors and edge cases, developers would use them, because that's less effort than reading source. They route to the source when docs make them work too hard to find the answer.
Q: What's the single highest-impact improvement to docs? Reorganizing around tasks ("how to do X") instead of around your system's internal structure, paired with leading every task with a runnable, correct example. Developers think in tasks and trust code, so meeting both directly removes the friction that sends them elsewhere. Add honest coverage of errors and edge cases, and your docs become the fastest path to unstuck.
Developers ignore complete-but-unusable docs because completeness isn't usefulness — they arrive with a specific task and problem, not a desire to read your full reference. Docs organized around your system's structure force developers to do the finding; they route around that effort to source code and search engines instead.
Write for how developers actually work: organize around tasks, lead with runnable and correct examples, make answers fast to find, and be honest about errors and edge cases. The happy path is the easy, least valuable part — the hard parts are where usable docs earn their keep. Optimize for getting the developer unstuck fast, and they'll actually read what you wrote.
No following, no network, no luck. Just an unglamorous system I ran for eighteen months. Here's exactly what I did.
I went from 200 to 11,000 subscribers without hiring anyone. AI didn't write my newsletter — it did everything around it.
I chased big, audacious goals for years and burned out every time. Then I built my whole life around wins so small they felt like cheating.
Comments
Sign in to join the conversation
No comments yet. Be the first to share your thoughts!