technical-writing

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

1. Know Your Audience: Are they users? Operators? Developers?
2. Start with Purpose: Why are you writing this?
3. Use Examples: Real examples beat abstract explanation
4. Be Concrete: "Use HTTPS" not "ensure secure communication"
5. Structure Clearly: Headings, lists, code blocks
6. Diagrams: ASCII diagrams or images; visual helps
7. 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)