oxidecomputer Diátaxis documentation framework
You write and review documentation according to the Diátaxis framework by Daniele Procida (https://diataxis.fr). Diátaxis identifies four modes of documentation, each serving a distinct user need. Never mix modes within a single document.
The source material in ${CLAUDE_SKILL_DIR}/diataxis-documentation-framework/
is the RST source of the Diátaxis website itself. It is structured according to
its own principles: the pages on each documentation type are reference, the
compass and workflow pages are how-to guides, the foundations and map pages are
explanation, and the start-here page is a tutorial. Study the source not just
for what it says, but for how it's written.
The compass: classifying content
Ask two questions to determine which mode content belongs to:
| Content... | ...serves the user's... | ...belongs to |
|---|---|---|
| informs action | acquisition of skill | tutorial |
| informs action | application of skill | how-to guide |
| informs cognition | application of skill | reference |
| informs cognition | acquisition of skill | explanation |
The four modes at a glance
Tutorial — a lesson. Learning-oriented. The reader acquires skill by doing things under your guidance. You are the teacher; all responsibility for success is yours. Minimize explanation. Focus on concrete steps and visible results.
How-to guide — a recipe. Goal-oriented. The reader already has competence and needs to accomplish a specific real-world task. No teaching, no explanation. Address the user's problem, not the tool's features.
Reference — a map. Information-oriented. Austere, neutral, complete technical description of the machinery. Structure mirrors the thing it describes. One consults reference; one does not read it.
Explanation — a discussion. Understanding-oriented. Provides context, background, reasoning, and connections. Answers "why?" questions. The only mode where opinion, alternatives, and history belong.
When to read the source material
Read the relevant page before writing or reviewing documentation of that type.
All paths are relative to ${CLAUDE_SKILL_DIR}/diataxis-documentation-framework/.
| Task | Read |
|---|---|
| Quick overview of the framework | start-here.rst |
| Writing or reviewing a tutorial | tutorials.rst |
| Writing or reviewing a how-to guide | how-to-guides.rst |
| Writing or reviewing reference docs | reference.rst |
| Writing or reviewing explanatory docs | explanation.rst |
| Unsure what type of doc to write | compass.rst |
| Distinguishing tutorials from how-tos | tutorials-how-to.rst |
| Distinguishing reference from explanation | reference-explanation.rst |
| Organizing a large documentation set | complex-hierarchies.rst |
| Understanding the theory behind Diátaxis | foundations.rst, map.rst |
| Thinking about documentation quality | quality.rst |
| Workflow: applying Diátaxis iteratively | how-to-use-diataxis.rst |
Do not read HTML files or images. The canonical source material is the .rst
source files, and all other files in the source are of limited value for your
comprehension of the framework.
Applying this skill
When asked to write documentation:
- Classify the content using the compass table above.
- Read the relevant source page for the mode you're writing in.
- Write following the principles in that page.
- Verify that you haven't mixed modes. If a section drifts into another mode (e.g., explanation creeping into a how-to guide), split it out or remove it.
When asked to review documentation:
- Classify each section by mode.
- Read the relevant source pages.
- Assess whether each section follows the principles for its mode.
- Report mode violations, mixed content, and structural issues.
$ARGUMENTS