Documentation
Creates, structures, and reviews technical documentation following the Diátaxis...
Install
npx skills add mcollina/skills --skill documentation -g -a claude-code -y- Repository
- mcollina/skills2k
- Category
- Writing
- Updated
- 8d ago
- License
- MIT
- Context cost
- Lightabout 1,179 tokens
- Runs scripts
- No, instructions only
What it does
Creates, structures, and reviews technical documentation following the Diátaxis framework (tutorials, how-to guides, reference, and explanation pages). Use when a user needs to write or reorganize docs, structure a tutorial vs. a how-to guide, build reference docs or API documentation, create explanation pages, choose between Diátaxis documentation types, or improve existing documentation structure. Trigger terms include: documentation structure, Diátaxis, tutorials vs how-to guides, organize docs, user guide, reference docs, technical writing.
When to use
Use this skill when you need to create, review, or improve technical documentation following the Diátaxis framework. Examples include:
- Creating user guides
- API documentation
- Tutorial content
- Restructuring existing documentation to better serve different user needs and contexts
Instructions
Organize documentation into four distinct types, tutorials, how-to guides, reference material, and explanations, each serving different user needs and contexts.
Always ask clarifying questions about the user's context, audience, and goals before creating documentation.
Step 1, Identify the documentation type
Use the following decision checklist based on user signals:
| User signal | Documentation type |
|---|---|
| "I'm new to X and want to learn it" / "walk me through" | Tutorial |
| "How do I…?" / "I need to accomplish X" | How-to guide |
| "What are the parameters/options/syntax for X?" | Reference |
| "Why does X work this way?" / "Help me understand X" | Explanation |
Quick decision tree:
- Is the user learning by doing for the first time? → Tutorial
- Do they need to solve a specific problem they already understand? → How-to guide
- Do they need technical facts to look up? → Reference
- Do they want conceptual background? → Explanation
Step 2, Apply type-specific patterns
Tutorials (learning-oriented)
- Title pattern: Start with a verb, "Build your first X", "Create a Y from scratch"
- Structure: Goal → Prerequisites → Numbered steps → Immediate verifiable result at each step → Final outcome
- Minimise explanation; maximise doing
- Every step must produce a visible, testable result
- Validation: A beginner must be able to complete the tutorial without external help
