documentation

<!-- TOKEN BUDGET: 160 lines / ~480 tokens -->

# Documentation Generation

Generate accurate, useful documentation that serves its audience. API docs for developers, guides for users, architecture docs for maintainers.

**The documenter agent references this skill for systematic documentation generation.**

## When to Use

- After implementing new features with public interfaces
- When making breaking changes
- When adding complex algorithms or business logic
- Before shipping a phase or milestone
- When documentation is flagged as incomplete

## Documentation Types

### 1. Code Documentation (Inline)

Document non-obvious code for developers reading the implementation.

**What to document:**
- Complex algorithms and business logic
- Non-obvious design decisions
- Workarounds and edge cases
- Performance considerations

**What NOT to document:**
```python
# BAD: Obvious
x = x + 1  # increment x

# GOOD: Explains why
# Cache invalidation here because user permissions
# affect multiple downstream services
invalidate_permission_cache(user.id)
```

**Format:** Docstrings with parameters, returns, exceptions, and examples for functions. Purpose and responsibilities for classes. Overview for modules.

### 2. API Documentation

Help developers use public interfaces correctly.

**Per endpoint/function:**
- Description (one sentence)
- Parameters with types and constraints
- Return values
- Error conditions
- At least one realistic example
- Authentication/authorization requirements (for APIs)

**Checklist:**
- [ ] All public functions/endpoints documented
- [ ] Parameter types and constraints specified
- [ ] Return values described
- [ ] Error conditions documented
- [ ] At least one example per function

### 3. Architecture Documentation

Help developers understand system design and make consistent changes.

**Components:**
- System overview with component diagram
- Each component's responsibility
- Data flow (with mermaid diagrams if complex)
- Key design decisions with