Technical Writing Basics: How to Write Docs People Actually Read
Most technical documentation fails not because it is inaccurate, but because it is unreadable. Long sentences, passive voice, and walls of text cause readers to skim, miss steps, and give up.
Lead with the Action
Put the most important information first. Readers want to do something — not read a paragraph of history before the first instruction.
Before: The authentication system in this application is based on OAuth 2.0, which is an industry-standard protocol...
After: To authenticate, POST to /auth/token with your client credentials. You will receive a bearer token valid for 24 hours.
Use Active Voice
| Passive (avoid) | Active (prefer) |
|---|---|
| The file should be saved | Save the file |
| An error will be thrown if... | The function throws an error if... |
| The token must be included | Include the token in the header |
One Idea Per Sentence
When a sentence exceeds 25 words, look for a split. Single-idea sentences are faster to read, easier to translate, and less likely to be misunderstood.
Use Numbered Lists for Sequences
When order matters, use a numbered list. Never use a paragraph to describe a sequence — readers skim paragraphs and miss steps.
Write for Scanning
Headings, code blocks, and bold text should carry the key information. A reader should understand the gist from headings alone.
Code Examples Over Prose
For technical content, a code example is worth ten paragraphs. Show the actual command, the actual JSON payload, the actual function call. Readers copy code; they skim prose.