# Documentation Writing

> Create clear, accurate, maintainable technical documentation.

## When to Use
- README files, API docs, architecture docs
- User guides, setup instructions, runbooks
- "Document this" / "write docs for"

## Approach
1. **Identify the audience** — developer? user? operator? executive?
2. **Start with the 30-second version** — what is this, why does it exist, how do I start?
3. **Show, don't tell** — code examples > prose descriptions
4. **Structure by task, not by feature** — "How to deploy" not "Deployment module"
5. **Include the unhappy path** — what to do when things go wrong
6. **Keep examples runnable** — every code block should work if copy-pasted

## Documentation Structure
```
# Project Name
One-sentence description.

## Quick Start (< 60 seconds to first result)
## What It Does (features, not implementation)
## Installation (every step, no assumptions)
## Usage (task-based, with examples)
## Configuration (every option, with defaults)
## Troubleshooting (common issues + fixes)
## API Reference (if applicable)
## Contributing (if applicable)
```

## Common Mistakes
- Writing for yourself, not the reader — the reader doesn't have your context
- Assuming prerequisites — state every dependency, every version, every OS assumption
- Stale examples — examples that don't work destroy trust faster than no docs at all
- Wall of text without structure — scannable headings and code blocks, not paragraphs
