Technical Writing Guide: Docs, API References & Clarity
Technical7 min readMay 2026
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."
The difference between accurate and useful
Technical writing is judged by whether the reader can complete the task, not by whether every sentence is technically true. A reference manual that lists every API parameter in alphabetical order is accurate; a quickstart that gets the reader from zero to a working "hello world" in five minutes is useful. Most teams overinvest in accuracy and underinvest in useful. The result is documentation that exists, satisfies a checklist, and is never read.
The four document types and when to use each
- Tutorial — learning-oriented. "How do I get started?" Hand-holds the reader through a complete, working example. No branching, no choices, no "if you prefer X you can Y".
- How-to guide — task-oriented. "How do I accomplish X?" Assumes the reader knows the basics and has a specific goal.
- Reference — information-oriented. "What does parameter Y do?" Exhaustive, accurate, structured for lookup, not reading.
- Explanation — understanding-oriented. "Why does the system work this way?" Background, design rationale, trade-offs.
This taxonomy comes from the Diátaxis framework. Mixing types in a single document is the most common reason docs feel "off" — a tutorial that suddenly becomes a reference, or a how-to that meanders into philosophy.
Sentence-level rules that compound
- Use active voice ("Run the command" not "The command should be run").
- One idea per sentence. If you used and twice, split it.
- Define jargon at first use, link to a glossary, then use the term freely.
- Imperative for instructions ("Click Save"), declarative for descriptions ("The Save button writes to disk").
- Numbers under ten as words, ten and above as digits — except in code, technical specs, and tables.
- Avoid "simply", "just", "obviously", "easy". They alienate readers who find it hard.
A common failure mode
"It worked on my machine" docs: written by the person who built the feature, who unconsciously skips the three setup steps they have already done. Mitigation: have someone unfamiliar with the system run through the doc on a fresh machine and flag every place they had to guess.
Maintenance beats authoring. Stale documentation is worse than missing documentation because it actively misleads. Tie doc updates to the same PR that changed the code.