Diataxis

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:

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: