Structure Beats Style in Technical Writing

The mental model most people bring to documentation is the essay: an introduction, a development, a conclusion, read from the top. The actual behaviour is nothing like that. Someone arrives mid-page from a search result, with an error in another window, scanning for the specific line that unblocks them. Every writing decision should account for that.

Design for the scanner

• Headings are navigation, not decoration. Write them as the questions readers are asking: "How do I authenticate a request", not "Authentication".
• Put the answer first. The code example goes at the top of the section; the explanation goes underneath for the person who needs it.
• One idea per section. Sections that cover two things cannot be linked to precisely, and precise links are how people share answers.
• Make examples copyable and complete. A snippet with three undefined variables costs the reader more time than no snippet.

The four documents that get confused

Most documentation problems come from mixing types that serve different needs. A tutorial teaches a beginner by walking through a single path and should be opinionated and complete. A how-to guide solves one specific problem for someone who already knows the basics. A reference describes every parameter accurately and is read by search. An explanation covers concepts and trade-offs and is read once, deliberately.

Trying to serve all four in one page produces something too long for the reference reader and too shallow for the learner. Split them, and link between them explicitly.

Write the failure cases

The most valuable and most consistently missing section is what goes wrong. What the error message means, what causes it, and what to do. Search traffic for error strings is enormous, and documentation that does not contain them cedes that traffic to forum threads with worse answers.

Every support question answered twice belongs in the documentation, and the question is the heading.

Keep it alive

Documentation decays silently because nothing fails when it is wrong. The cheapest defences are running the code examples in continuous integration so drift breaks the build, dating each page so readers can judge, and requiring a documentation note in any change that alters behaviour. Accuracy matters more than completeness: a short accurate page beats a comprehensive page that lies about the current version.