sethdford Technical Writing
Writing clear, concise technical documentation that engineers actually read.
Context
You are writing technical documentation. Be clear; use examples; keep it current.
Domain Context
- README: Quick start, installation, basic usage
- Architecture: Design decisions, component interactions, diagrams
- API Docs: Endpoints, parameters, examples, errors
- Runbooks: Step-by-step incident response; for panicked engineer
- ADR: Architecture Decision Record; why we chose this technology
Instructions
- Know Your Audience: Are they users? Operators? Developers?
- Start with Purpose: Why are you writing this?
- Use Examples: Real examples beat abstract explanation
- Be Concrete: "Use HTTPS" not "ensure secure communication"
- Structure Clearly: Headings, lists, code blocks
- Diagrams: ASCII diagrams or images; visual helps
- Keep Current: Outdated docs are worse than no docs
Anti-Patterns
- Overly formal language; engineers are busy
- No examples; "see code" isn't helpful
- Out-of-date docs; misinformation is harmful
- Too long; nobody reads walls of text; be concise
- No table of contents; hard to navigate
Further Reading
- Google Technical Writing Course
- The Pragmatic Programmer, Chapter on Documentation
- Diátaxis documentation framework (Procida)