enhance-docs
npx machina-cli add skill kasperjunge/agent-resources/enhance-docs --openclawFiles (1)
SKILL.md
2.2 KB
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
Source
git clone https://github.com/kasperjunge/agent-resources/blob/main/skills/development/codebase-maintenance/enhance-docs/SKILL.mdView on GitHub Overview
Enhance Docs updates documentation to be up to date, coherent, and focused on users' jobs-to-be-done. It prioritizes clarity with less content and higher signal, guiding contributors to map jobs, verify accuracy, and deliver ranked improvements.
How This Skill Works
The process maps user jobs, checks docs against current behavior and changes, then simplifies and restructures content. It fixes coherence, adds minimal examples only where needed, and delivers prioritized improvements based on impact on user success and confusion reduction.
When to Use It
- Documentation is outdated or inconsistent with current product behavior.
- Users report confusion or high cognitive load when following docs.
- A new release requires updating docs and reorganizing sections.
- Need to reduce doc length while preserving essential guidance.
- You want to improve cross-links and coherence across related topics.
Quick Start
- Step 1: Map top 3-5 user jobs and identify the docs that enable each.
- Step 2: Check freshness and accuracy against current behavior, APIs, and changes.
- Step 3: Simplify, restructure, and deliver ranked improvements with consistent cross-links.
Best Practices
- Trim before adding: remove noise to expose core guidance.
- Structure by jobs and outcomes, not features.
- Use short paragraphs, clear headings, and predictable structure.
- Prioritize steps, outcomes, and decision points for high signal.
- Maintain consistent terminology and add cross-links across topics.
Example Use Cases
- Reorganize a developer guide from feature lists to JTBD-focused sections mapped to top user jobs.
- Update API docs to reflect current behavior and link to the changelog for context.
- Collapse long checklists into concise, actionable step-by-step guides.
- Add minimal, targeted examples only where they unblock user action.
- Standardize terminology across docs and add cross-links to authoritative sources.
Frequently Asked Questions
Add this skill to your agents
