---
name: documentation-writer
description: Write or update technical documentation for code, APIs, or systems. Use when asked to document a module, write a README, generate API docs, or update existing documentation.
license: MIT
---

## Overview

You write documentation that developers will actually read. That means concrete examples over abstract descriptions, and answering the question "how do I use this?" before "what is this?".

## Process

1. **Read the source first.** Load the actual code before writing a single word. Documentation that doesn't match the implementation is worse than no documentation.

2. **Identify the documentation type:**
   - **README** — for projects and repositories
   - **Module/API docs** — for functions, classes, endpoints
   - **Architecture docs** — for system design and component relationships
   - **Runbook** — for operational procedures

3. **For READMEs**, follow this structure:
   ```
   # Project Name
   One sentence: what it does and who it's for.

   ## Quick Start
   The fewest possible steps to get something working.
   Code first. Explanation second.

   ## Installation
   ## Usage
   ## Configuration
   ## API Reference (if applicable)
   ## Contributing
   ## License
   ```

4. **For function/class docs**, write docstrings that include:
   - What the function does (one line)
   - Parameters: name, type, description, whether optional
   - Return value: type and description
   - Exceptions it may raise
   - One usage example

5. **Write the example first.** If you cannot write a concrete 5-line example of how to use something, you don't understand it well enough to document it. Go back to step 1.

6. **Verify accuracy.** Read your documentation and check every claim against the code. If you wrote "`returns a list of strings`" and the code returns a dict, fix it.

## Rationalizations

| Excuse | Rebuttal |
|--------|----------|
| "The code is self-documenting" | No code is self-documenting to someone seeing it for the first time. Write the docs. |
| "I'll add examples later" | Documentation without examples is theory. Write the example now. |
| "The function signature explains it" | Type hints say what the types are, not what the function does or why. |

## Verification

- [ ] Every documented function has at least one usage example
- [ ] Parameter types and return types are correct (verified against the source)
- [ ] Quick Start section in README can be followed by a new developer with no prior context
- [ ] No documentation contradicts the actual implementation