diataxis

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:

1. Classify the content using the compass table above.
2. Read the relevant source page for the mode you're writing in.
3. Write following the principles in that page.
4. 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:

1. Classify each section by mode.
2. Read the relevant source pages.
3. Assess whether each section follows the principles for its mode.
4. Report mode violations, mixed content, and structural issues.

$ARGUMENTS