tools-only 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
- Map jobs-to-be-done
- List top 3-5 user jobs and the docs that should enable each.
- Check freshness and accuracy
- Compare docs against current behavior, APIs, and recent changes.
- Simplify and restructure
- Remove redundancy, collapse long lists, and apply progressive disclosure.
- Improve coherence
- Align terminology, fix contradictions, and add consistent cross-links.
- Clarify with examples
- Add minimal examples only where they unblock action.
- 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