Technical writing is the difference between users who succeed and users who file tickets. Good docs cut support cost, increase activation, and turn reluctant readers into power users. The principles are simple — the discipline is hard.
Documentation Types and Patterns
| Type | Goal | Format | Tone |
|---|---|---|---|
| Tutorial | Teach a concept by doing | Step-by-step, narrative | Encouraging |
| How-to guide | Solve a specific task | Numbered steps | Direct |
| API reference | Lookup parameters & responses | Tables, examples | Neutral |
| Explanation | Understand "why" and concepts | Prose, diagrams | Conversational |
| Release notes | What changed and when | Categorized lists | Factual |
Clarity Rules
- One idea per sentence. If "and" appears more than twice, split.
- Active voice. "The server returns a token" beats "A token is returned."
- Define jargon on first use. Then assume it's known.
- Show before telling. Code example first, explanation after.
- Be deterministic. Replace "should work" with "works" or list the conditions.
API Reference Pattern
A reliable API reference follows the same shape on every endpoint: short purpose, HTTP method and path, parameter table with types and required flags, headers if relevant, request example, response example for the happy path, and every error status with a one-line cause. Predictability lets developers scan; surprises waste their time.
Style and Tone
Use second person, present tense, and imperative for instructions. Sentence-case headings. Numbers as digits ("3" not "three") above ten and in code contexts. Code formatting for everything code-like — file names, commands, environment variables. And version your docs alongside your product: "v3.2.1" beats "the new version."
Check Doc Readability
Run your documentation through a Flesch-Kincaid grade check.
Readability Checker →