technical-writinglisted

Technical writing succeeds when a specific reader can do a specific thing after reading. Decide who the reader is and what they are trying to do before writing a heading. Every later choice (structure, depth, examples, tone) follows from that. ## Before drafting - **Reader**: their role, what they already know, what they are trying to do, how much time they have. "A backend developer integrating our API for the first time, in an afternoon" beats "developers". - **Purpose**: teach a skill (tutorial), get a task done (how-to), look something up (reference), or understand why (explanation). Mixing two in one page produces a page that serves neither. Split. - **Outcome**: the sentence the reader should be able to say afterwards: "I can rotate an API key without downtime." ## The four document types **Tutorial** (learning-oriented): a guaranteed-to-work path from nothing to a result. Numbered steps, every command shown, expected output shown, no choices offered, no explanations beyond one line ("this creates the config file"). Test it end to end on a clean machine. **How-to guide** (task-oriented): assumes competence, solves one problem. Title as the goal ("Rotate an API key"). Prerequisites, steps, verification, what can go wrong. Offer choices only where the reader's situation differs. **Reference** (information-oriented): complete, consistent, dry. Same structure for every entry (signature, parameters with types and defaults, return, errors, example). Generated from sourc