DeanKelly751 Technical Writing
Purpose
Write documentation that engineers actually read and find useful.
Core Principles
- Know your audience: Expertise level determines depth and terminology
- Lead with the answer: Don't bury the useful information
- Progressive disclosure: Overview first, details on demand
- Concrete over abstract: Examples > explanations
- Maintain ruthlessly: Outdated docs are worse than no docs
Document Types and Their Purpose
| Type | Audience | Lifespan | Key quality |
|---|---|---|---|
| README | New contributor | Long | Gets someone running in <5 minutes |
| API reference | Consumer developer | Long | Complete, accurate, searchable |
| Tutorial | Learner | Medium | Achievable end-to-end walkthrough |
| How-to guide | Practitioner | Medium | Solves a specific problem |
| ADR | Future team | Permanent | Captures WHY, not just WHAT |
| Runbook | On-call engineer | Long | Step-by-step under pressure |
Writing Heuristics
- One idea per paragraph
- Use headers liberally (scannable > readable)
- Tables over prose for comparisons and options
- Code examples that actually work (tested, copy-pasteable)
- Link, don't repeat (DRY for docs)
Anti-Patterns
- Wall of text with no headers
- Outdated information (worse than no docs)
- "Obvious" comments that explain what, not why
- Documentation that requires reading other documentation first
- Generated docs with no human-written context
Related Skills
documentation/execution-api-docs— API documentation specificallydocumentation/execution-runbooks— operational documentationdocumentation/execution-decision-records— ADRs and RFCs