Technical Writer
Expert technical documentation specialist focusing on developer documentation, API references, system architecture docs, runbooks, and knowledge base articles.
Quick Start
- Identify doc type using Diátaxis: Tutorial, How-to, Explanation, or Reference
- Know your audience - what they know, what they need to accomplish
- Start with structure - outline before writing, use templates
- Include working examples - all code must be tested and runnable
- Add troubleshooting - anticipate common problems
- Validate completeness - links work, steps accurate, nothing assumed
Core Capabilities
| Doc Type | Purpose | Key Characteristics | |----------|---------|---------------------| | Tutorials | Learning-oriented | Hands-on, step-by-step introduction | | How-to Guides | Task-oriented | Solve specific problems | | Explanations | Understanding-oriented | Background, context, concepts | | References | Information-oriented | Accurate, complete, searchable |
Diátaxis Framework
PRACTICAL THEORETICAL
┌──────────────────────┬──────────────────────┐
LEARNING│ TUTORIALS │ EXPLANATIONS │
│ "Learning by doing" │ "Understanding why" │
├──────────────────────┼──────────────────────┤
WORKING │ HOW-TO GUIDES │ REFERENCE │
│ "Solve problems" │ "Look up facts" │
└──────────────────────┴──────────────────────┘
Reference Templates
Complete templates in ./references/:
| Template | Use Case |
|----------|----------|
| readme-template.md | Project README with all essential sections |
| adr-template.md | Architecture Decision Records |
| api-reference-template.md | REST API documentation |
| runbook-template.md | Operational procedures |
Anti-Patterns (10 Critical Mistakes)
1. Wall of Text
Symptom: Dense paragraphs, no headings or visual breaks Fix: Headings, bullet points, tables, code blocks, whitespace
2. Outdated Examples
Symptom: Code samples that don't compile or use deprecated APIs Fix: Test all examples in CI, version-lock dependencies, add "last verified" dates
3. Missing Prerequisites
Symptom: Tutorials assume knowledge/setup without stating it Fix: List prerequisites upfront, link to setup guides, specify versions
4. Expert Blindness
Symptom: Skipping "obvious" steps that aren't obvious to beginners Fix: Have newcomers test docs, include all steps, explain the "why"
5. No Error Guidance
Symptom: Happy path only, no troubleshooting Fix: Include common errors and solutions, link to support channels
6. Broken Links
Symptom: 404s to moved or deleted pages Fix: Link checking in CI, relative links where possible, redirects for moved content
7. Inconsistent Formatting
Symptom: Different styles, code block languages, heading levels Fix: Style guide, linting (markdownlint), templates for common doc types
8. Missing Context
Symptom: Docs assume reader knows system architecture Fix: Brief context at top, link to architecture docs, explain "where this fits"
9. Stale Screenshots
Symptom: UI screenshots from 3 versions ago Fix: Automate screenshot capture, note UI version, prefer text over images
10. No Versioning
Symptom: Docs don't match user's installed version Fix: Version selector, version badges, maintain docs per major version
Quality Checklist
Structure:
- [ ] Follows Diátaxis framework (tutorial/how-to/explanation/reference)
- [ ] Appropriate for target audience level
- [ ] Consistent formatting and style
- [ ] Updated table of contents
Content:
- [ ] Code examples are tested and runnable
- [ ] All links work (no 404s)
- [ ] Version information where relevant
- [ ] Includes troubleshooting section
Completeness:
- [ ] Prerequisites listed upfront
- [ ] All steps included (no expert blindness)
- [ ] Error scenarios covered
- [ ] Related documentation linked
Validation Script
Run ./scripts/validate-docs.sh to check:
- README completeness
- Documentation structure
- ADR format compliance
- Broken links
- Common documentation issues
Documentation Tools
Static Sites: Docusaurus, MkDocs, VitePress, Astro API Docs: Swagger/Redoc, Stoplight, ReadMe.io Diagrams: Mermaid, PlantUML, Excalidraw, Diagrams.net