About documentation
documentation is a skill for creating, reviewing, and restructuring technical documentation using the Diátaxis framework. It helps documentation authors distinguish tutorials, how-to guides, reference material, and explanations, and asks them to clarify audience and goals first.
Key features
- 01Diátaxis documentation framework
- 02Four distinct documentation types
- 03Type-specific structure guidance
- 04Validation checks for each type
Use cases
- 01Creating a beginner tutorial
- 02Writing a task-focused how-to guide
- 03Organizing API reference material
- 04Restructuring documentation by reader need
Install
Copy the command and run it in a terminal.
npx skills add https:/After installing, type/documentationin Claude Code to confirm it loaded.
Bundled filestile.json
Details
From the project READMEWhen 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
Example intro:
"In this tutorial, you will build a simple REST API using Express. By the end, you will have a running server that responds to GET requests. No prior Express experience is needed."
How-to guides (problem-oriented)
- Title pattern: Frame as a task — "How to configure X", "How to deploy Y to Z"
- Structure: Goal statement → Assumptions/prerequisites → Numbered steps → Expected result
- Assume baseline knowledge; skip conceptual explanations
- Allow for variation; note alternatives where they exist
- Validation: An experienced user can complete the task without confusion or backtracking
Example intro:
"This guide shows how to add JWT authentication to an existing Express app. It assumes you have a working Express server and basic familiarity with middleware."
Reference (information-oriented)
- Title pattern: Name the thing — "Configuration options", "API endpoints", "CLI flags"
- Structure: Consistent repeatable format per entry (name → type → default → description → example)
- State facts; avoid instruction beyond minimal usage examples
- Keep current; version-stamp if needed
- Validation: A user can look up a specific fact in under 30 seconds without reading surrounding content
Example entry:
timeout(integer, default:5000) Maximum time in milliseconds to wait for a response before the request fails. Example:{ timeout: 3000 }
Explanations (understanding-oriented)
- Title pattern: Frame as a concept — "How X works", "Understanding Y", "Why Z is designed this way"
- Structure: Context → Core concept → Alternatives/trade-offs → Higher-level perspective
- Avoid step-by-step instruction or technical specification
- Validation: After reading, the user can explain the concept in their own words and understands the rationale behind design decisions
Example intro:
"Authentication and authorisation are often confused. This page explains the distinction, why both matter, and how common patterns (sessions, tokens, OAuth) approach each concern differently."
Step 3 — Maintain separation and integration
- Keep each document a single type — don't mix tutorial steps with reference tables or conceptual digressions
- Cross-link between types: a tutorial can link to the relevant reference page; a how-to guide can link to an explanation for background
- Use consistent headings and terminology across all types so users can navigate the full documentation system
Step 4 — Validate before delivering
| Type | Validation check |
|---|---|
| Tutorial | Can a beginner complete it end-to-end without external help? |
| How-to guide | Does it solve the stated problem for an experienced user? |
| Reference | Can the user find a specific fact in under 30 seconds? |
| Explanation | Does the user understand the why, not just the what? |