enhance-docs

---
name: enhance-docs
description: Use when documentation needs to be updated, clarified, or reorganized to better serve users' jobs-to-be-done with low cognitive load and high signal.
---

# Enhance Docs

## Overview
Improve documentation so it is up to date, coherent, and centered on users' jobs-to-be-done. Favor less content with higher clarity.

## Inputs (ask if missing, max 5)
- Docs scope (which files or sections)
- Primary audiences and their jobs-to-be-done
- Source of truth for product behavior (code, APIs, changelog)
- Recent changes or upcoming releases
- Constraints (tone, length, compliance, deadlines)

## Principles
- **Less is more**: reduce noise, keep only what helps users act.
- **Low cognitive load**: short paragraphs, clear headings, predictable structure.
- **High signal**: prioritize steps, outcomes, and decision points.
- **JTBD-first**: structure around what users are trying to accomplish.

## Workflow
1. **Map jobs-to-be-done**
   - List top 3-5 user jobs and the docs that should enable each.
2. **Check freshness and accuracy**
   - Compare docs against current behavior, APIs, and recent changes.
3. **Simplify and restructure**
   - Remove redundancy, collapse long lists, and apply progressive disclosure.
4. **Improve coherence**
   - Align terminology, fix contradictions, and add consistent cross-links.
5. **Clarify with examples**
   - Add minimal examples only where they unblock action.
6. **Deliver ranked improvements**
   - Prioritize changes by impact on user success and confusion reduction.

## Output Format
```
## Documentation Enhancement

### Context Summary
[1-3 sentences]

### JTBD Map
- Job: ... -> Docs: ... -> Success criteria: ...

### Issues (ranked)
1) [Issue] — impact: high, evidence: ...

### Proposed Changes (ranked)
1) [Change] — rationale: ...

### Quick Wins
- ...

### Open Questions
- ...
```

## Quick Reference
- Trim before adding.
- Structure by jobs and outcomes, not features.
- Keep headings short and action-oriented.

## Common Mistakes
- Adding more text instead of removing noise
- Mixing audiences in the same section
- Describing features without user tasks
- Missing cross-links or inconsistent terminology