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:

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.