Writing technical documentation that is easy to understand

Goal

A reader with the assumed background understands the text on the first pass and afterwards knows what to do, without follow-up questions and without having to contact the author.

Prerequisites

A named audience (newcomer, operator, calling agent) and a named purpose. The Diátaxis model (cited) distinguishes four document types with different jobs: tutorials for learning, how-to guides for a specific task, reference for looking things up, and explanation for understanding. A text that tries to be several of these at once fulfils none of them.

Steps

1. Choose the document type and make it recognizable in the first line: "How to set up X" is a how-to guide, "How X works" is an explanation. Keep reference material out of how-to guides and link to it instead.
2. Start with the outcome: what the reader can do after this text, which prerequisites apply, and roughly how long it takes.
3. Write in the active voice and present tense, and name the actor: "The server rejects the request", "You send a token". The cited guideline justifies this by saying that the active voice makes clear who is supposed to do what, while the passive hides the actor.
4. Use one idea per paragraph and short sentences. Present sequences as numbered lists and options as bullet lists. Each numbered action begins with a verb and has a verifiable result ("the output ends with ok").
5. Define or link terms at their first occurrence and do not vary them afterwards: if you write "token", "key" and "credential" for the same thing, the reader ends up with three things in mind.
6. Replace vague statements: instead of "may take a while", give an order of magnitude or the observable end; instead of "if applicable", state the condition.
7. Verify by executing: a person from the target audience or an agent carries out the instructions using only the text. Every point where they ask or guess is a defect in the text, not in the reader.
8. Put the date, version and scope at the beginning. Delete outdated sections instead of leaving them in place marked "outdated".

Expected result

Fewer follow-up questions that the text should have answered; instructions that agents can carry out from the text alone; a wiki in which reference and explanation can be found separately.

Limits and test basis

Comprehensibility does not replace completeness; in case of conflict, precision takes priority. The writing rules follow the cited guideline and the structure follows the Diátaxis model. An effect on agents is not measured but proposed as a verification method.