A common, well-intentioned goal in technical documentation is comprehensiveness — covering every feature, every option, every edge case, thoroughly and accurately. This goal, pursued without a separate consideration of how documentation actually gets used, tends to produce documentation that's technically complete and practically hard to use, because most readers arrive at documentation with one specific question and a limited amount of patience for finding the answer, not with an intention to read the document from beginning to end. A detailed editorial reference is the Google developer documentation style guide.
The difference between reference and task-oriented documentation
A useful distinction, widely discussed in technical writing practice, separates documentation into different types serving genuinely different reader needs: reference documentation (a complete, accurate, systematically organized description of every option and behavior, optimized for being looked up rather than read straight through) and task-oriented documentation (a guide to accomplishing one specific, common goal, optimized to be read start to finish by someone trying to do that particular thing). A common failure is writing only reference documentation and expecting it to also serve the task-oriented need — a new user trying to accomplish a specific first task, faced with a complete, systematically organized reference instead of a direct guide to their specific goal, often struggles to identify which of many documented options are actually relevant to what they're trying to do. The same coordination problem appears when work is divided across customers, and the link offers practical guidance.
This distinction connects directly to the README guide discussed elsewhere on this shelf: a good README is almost entirely task-oriented (get this specific, common thing working), while fuller reference documentation, linked from the README rather than crammed into it, serves the different, later need of a reader who already has the basics working and needs to look up a specific option or edge case.
Writing for scanning, not just for reading
Most technical documentation is scanned before it's read — a reader with a specific question skims headings, code samples, and bolded terms looking for the section that addresses their actual need, before committing to reading any section closely. Documentation structured with this scanning behavior in mind — clear, specific headings that describe what's in each section rather than generic ones, code examples that can be understood at a glance without necessarily reading every surrounding paragraph first, and a clear visual distinction between required and optional information — serves this common reading pattern far better than a well-written but undifferentiated wall of prose that assumes a reader willing to read every word in order.
- Distinguish task-oriented documentation (how do I accomplish this specific goal) from reference documentation (what does every option do) — most readers need one or the other at a given moment, not both blended together.
- Write headings specific enough to be useful when scanned in isolation — a heading like “Configuration” is less useful for scanning than “Configuring a custom timeout.”
- Lead each section with the information most readers of that section actually need, before background or edge-case detail that a smaller subset of readers will care about.
- Test documentation the same way the README guide elsewhere on this shelf suggests testing setup instructions — have someone unfamiliar with the project actually try to accomplish a task using only the docs, and note where they get stuck.
Why examples often do more work than prose
A working code example, for most technical audiences, communicates faster and more reliably than an equivalent amount of prose describing the same usage — developers reading documentation are frequently looking for something to adapt directly, and a correct, runnable example serves that need more directly than a careful prose description they'd have to translate into code themselves. This doesn't mean prose explanation is unnecessary — an example alone often doesn't convey why a particular approach is recommended, or what trade-off it represents — but a well-chosen example paired with brief explanation tends to outperform either extreme on its own.
Paired with the README and API-design guides discussed elsewhere on this shelf, this is really the same underlying discipline applied at a larger scale: designing for the reader's actual moment of need, rather than for the writer's sense of what a complete, well-organized account of the subject should look like.