diataxis

name	diataxis
description	Write technical documentation following the Diataxis framework by Daniele Procida. Use when writing, reviewing, or restructuring documentation to ensure correct separation of tutorials, how-to guides, reference, and explanation.

Diataxis Documentation Framework

Complete reference for the Diataxis framework — a systematic approach to technical documentation authoring by Daniele Procida. All content sourced verbatim from diataxis.fr.

When to Use This Skill

This skill should be triggered when:

• Writing documentation: Creating new docs pages of any type
• Reviewing documentation: Checking if content is in the right place and follows the right form
• Restructuring documentation: Reorganizing existing docs into proper Diataxis categories
• Deciding content type: Determining whether something should be a tutorial, how-to, reference, or explanation
• Resolving confusion: Distinguishing tutorials from how-to guides, or reference from explanation

The Diataxis Compass

Use this decision table when you need to classify content:

If the content...	...and serves the user's...	...then it belongs in...
informs action	acquisition of skill	a tutorial
informs action	application of skill	a how-to guide
informs cognition	application of skill	reference
informs cognition	acquisition of skill	explanation

Two questions to ask:

1. Action or cognition? Is this about doing something or knowing something?
2. Acquisition or application? Is the user learning or working?

Full compass guidance: references/compass.md

The Four Documentation Types

Tutorials (learning-oriented)

• An experience guided by a tutor, where the learner acquires skills by doing
• Teacher holds nearly all responsibility — learner just follows directions
• Concrete steps, no choices, no branching, ruthlessly minimal explanation
• Language: "We will...", "First, do X. Now, do Y.", "Notice that...", "You have built..."

Full reference: references/tutorials.md

How-to Guides (goal-oriented)

• Directions that guide a competent user through a real-world problem
• Assumes the user already knows the basics and has a specific goal
• Can branch ("If this, do that"), addresses real-world conditions
• Language: "If you want X, do Y." Conditional imperatives.

Full reference: references/how-to-guides.md

Reference (information-oriented)

• Technical description of the machinery — austere, factual, structured like the code
• Consulted while working, not read cover-to-cover
• Neutral, objective. Describe and only describe. No teaching, no opinions.
• Language: "X does Y.", "You must use X.", lists, tables, warnings.

Full reference: references/reference.md

Explanation (understanding-oriented)

• Discursive treatment that permits reflection and deepens understanding
• Read after stepping away from work. Discusses why, provides context, weighs alternatives.
• Admits opinion and perspective. Makes connections across topics.
• Language: "The reason for X is...", "Consider...", analogies, history, alternatives.

Full reference: references/explanation.md

Critical Distinctions

The most common mistake in documentation is mixing types. Read these when boundaries are unclear:

• Tutorials vs How-to Guides: references/tutorials-how-to.md — The single most common conflation in software documentation. Tutorials are safe, contrived, teacher-led. How-to guides are real-world, user-led, assume competence.
• Reference vs Explanation: references/reference-explanation.md — Key test: would you consult this while working (reference) or after stepping away (explanation)?

Reference Files

All files in references/ contain the complete, unabridged content from diataxis.fr:

Getting Started

• references/index.md — Overview and introduction to Diataxis
• references/start-here.md — Getting started primer
• references/application.md — Applying Diataxis in practice

The Four Types (read before writing any documentation)

• references/tutorials.md (16K) — Complete tutorial guidance with all principles
• references/how-to-guides.md (11K) — Complete how-to guide guidance
• references/reference.md (6K) — Complete reference documentation guidance
• references/explanation.md (7K) — Complete explanation guidance

Practical Tools

• references/compass.md — The decision compass for classifying content
• references/how-to-use-diataxis.md — Workflow guidance for applying the framework

Theory & Principles

• references/theory.md — Theoretical foundations overview
• references/foundations.md — Foundational concepts underpinning Diataxis
• references/map.md — The Diataxis map and its relationships
• references/quality.md (11K) — Theory of functional vs deep quality in documentation

Boundaries & Edge Cases

• references/tutorials-how-to.md (14K) — Tutorials vs how-to guides (the most important distinction)
• references/reference-explanation.md — Reference vs explanation
• references/complex-hierarchies.md (8K) — Handling complex documentation structures

Meta

• references/colophon.md — About Diataxis itself

Working with This Skill

Before Writing a Page

1. Determine which Diataxis type it is using the compass above
2. Read the full reference file for that type (e.g., references/tutorials.md)
3. Follow the language patterns and structural rules for that type
4. Never mix types on a single page

When Reviewing Documentation

1. For each page, use the compass to verify its type
2. Flag any content that mixes types (e.g., explanation inside a how-to guide)
3. Check references/tutorials-how-to.md if tutorials and how-tos seem conflated
4. Check references/reference-explanation.md if reference and explanation seem blurred

When Restructuring

1. Read references/how-to-use-diataxis.md for the overall workflow
2. Read references/complex-hierarchies.md for handling large documentation sites
3. Classify every existing page using the compass
4. Move misplaced content to its correct type

Notes

• All reference content is Daniele Procida's original writing from diataxis.fr — do not paraphrase when the original words apply
• The reference files are the authority. When in doubt, re-read the relevant file.
• Source: https://diataxis.fr/ — Copyright Daniele Procida