| name | doc |
| description | Write or improve documentation using the Diataxis framework. Creates user-centered docs in four types - tutorials, how-to guides, reference, explanation. Use when writing docs, improving documentation, auditing docs, or when the user mentions Diataxis. |
Documentation Skill (Diataxis Framework)
Write documentation that serves user needs using the Diataxis framework.
Quick Reference
| User Need | Doc Type | User Mode | Content Focus |
|---|
| Learning | Tutorial | Study | Action (doing) |
| Goal completion | How-to Guide | Work | Action (doing) |
| Information lookup | Reference | Work | Cognition (knowing) |
| Understanding | Explanation | Study | Cognition (knowing) |
Decision Matrix
Use the Diataxis Compass to determine doc type:
Is the content about ACTION or COGNITION?
├── ACTION (practical steps, doing)
│ ├── For ACQUISITION (study/learning) → Tutorial
│ └── For APPLICATION (work/tasks) → How-to Guide
└── COGNITION (theoretical knowledge, thinking)
├── For APPLICATION (work/tasks) → Reference
└── For ACQUISITION (study/learning) → Explanation
Instructions
1. Determine Documentation Type
If type is specified: Use that type directly.
If audit is requested: Analyze existing docs against Diataxis principles. Report:
- What type each doc appears to be
- Whether content matches its apparent type
- Boundary violations (e.g., explanation bleeding into reference)
- Gaps in coverage
Otherwise, ask these questions:
- Does this inform the user's action (doing) or cognition (knowing)?
- Does it serve acquisition (study) or application (work)?
2. Apply Type-Specific Guidelines
Read the detailed guide for your documentation type:
3. Key Principles (All Types)
Do:
- Focus on user needs, not product features
- Keep boundaries clear between doc types
- Link to other doc types rather than mixing content
- Use language appropriate to the doc type
Don't:
- Mix learning content with task guidance
- Add explanation where description is needed
- Include reference details in tutorials
- Blur boundaries between doc types
4. Structural Guidelines
Naming conventions:
- Tutorials: "Getting started with X", "Learn to X"
- How-to: "How to X", "Configuring X for Y"
- Reference: "X API", "X configuration options"
- Explanation: "About X", "Understanding X", "Why X"
Landing pages for each section should:
- Provide overview of contents
- Use headings and snippets (not just lists)
- Group related items (max 7 items per group)
Common Anti-Patterns
| Problem | Symptom | Fix |
|---|
| Tutorial-as-reference | Lists all options | Remove options, show one path |
| How-to-as-tutorial | Teaches concepts | Move teaching to tutorial/explanation |
| Reference-as-explanation | Discusses "why" | Move discussion to explanation |
| Explanation-in-tutorial | Long digressions | Link to explanation, keep minimal |
Workflow Summary
- Identify the user need (learning/goal/info/understanding)
- Select doc type using the compass
- Read the detailed guide for that type
- Write following type-specific principles
- Review for boundary violations
- Link to related docs of other types
Further Reading
