diataxis

Diátaxis Documentation Framework

Most documentation problems stem from mixing different types of content in ways that serve nobody well. A tutorial that drifts into reference material loses beginners; a reference page with step-by-step instructions frustrates experts looking up specifics. Diátaxis solves this by identifying four distinct documentation modes, each serving a different user need at a different moment. Keeping these modes separate and well-executed is the foundation of documentation that actually works.

The Diátaxis Compass

Two fundamental axes classify all documentation:

	Acquisition (study/learning)	Application (work/doing)
Action	Tutorial	How-to Guide
Cognition	Explanation	Reference

Diagnostic questions:

1. Does this content involve practical steps (action) or theoretical knowledge (cognition)?
2. Is the user learning something new (acquisition) or applying existing skill (application)?

The answers place content in exactly one quadrant.

---

The Four Documentation Modes

1. Tutorials (Learning-oriented)

Purpose: Guide a learner through a series of steps to acquire skills and understanding.

Defining characteristics:

• The teacher takes full responsibility for the learner's success
• Learning happens through doing, not through explanation
• The learner follows a carefully designed path to a meaningful result

Effective tutorials: (A learner in acquisition mode needs confidence and momentum — these principles protect that.)

• Show the destination upfront — what the learner will accomplish
• Deliver visible results at every step — each action produces comprehensible output
• Maintain narrative expectations — "You will notice that...", "The output should look like..."
• Point out observable details — direct the learner's attention to important cues
• Target the "feeling of doing" — help learners discover rhythm and satisfaction
• Encourage repetition — design steps that reward being repeated
• Aspire to perfect reliability — learners must get the promised results every time