The Writing Process
| Item | Description |
|---|
1. Audience Analysis | Who, what they know, what they need. Developer vs manager vs end-user = different docs. |
2. Outline | Structure before writing. Headers only. Rearrange until flow makes sense. |
3. Draft | Write without editing. Separate creation from criticism. Get words down first. |
4. Revise | Cut 20%. Remove jargon. Shorten sentences. Read aloud — awkward phrasing audible. |
5. Review | Peer review. Can someone follow instructions without asking? If not, revise. |
Clarity Principles
| Item | Description |
|---|
Active Voice | 'The function returns a value' not 'A value is returned by the function.' |
Short Sentences | 15-20 words average. Vary length for rhythm. One idea per sentence. |
Present Tense | Documentation describes how things ARE: 'The API returns JSON' not 'The API will return JSON.' |
Imperative Mood | Instructions: 'Click Save.' Not 'You should click Save' or 'The user clicks Save.' |
Consistent Terms | Pick one term and stick to it. Don't alternate between 'directory' and 'folder.' |
Remove Hedging | 'Basically, essentially, just, simply' — delete these. They weaken writing. |
Document Types & Structure
| Item | Description |
|---|
Tutorial | Learning-oriented. Step-by-step. 'In this tutorial, you'll build a...' Start → middle → end. |
How-To Guide | Task-oriented. 'How to deploy a React app.' Steps to solve a specific problem. |
Reference | Information-oriented. API docs, config options, CLI commands. Lookup, not reading. |
Explanation | Understanding-oriented. 'How authentication works.' Background, context, design decisions. |
README | What, why, how (quick start), where (docs link), who (contributing). 5-minute read max. |
Style Guides
| Item | Description |
|---|
Google Developer Style | Comprehensive, free. Covers: word choice, formatting, HTML/CSS, inclusive language. |
Microsoft Style Guide | Enterprise-focused. Voice: warm + relaxed, crisp + clear, ready to lend a hand. |
Write the Docs | Community guide. Opinionated, practical, documentation-specific. |
Chicago Manual of Style | Book publishing. Authoritative. For long-form technical books. |
Pro Tip: Write for your reader, not for yourself. Before writing, answer: Who is reading this? What do they already know? What do they need to DO after reading? If you can't answer, stop and find out.