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.
apm install @kasperjunge/enhance-docs[](https://apm-p1ls2dz87-atlamors-projects.vercel.app/packages/@kasperjunge/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