The Diataxis Framework Explained: Four Types of Documentation

The Diataxis framework is a principled approach to structuring technical documentation. Created by Daniele Procida, it argues that all technical documentation serves one of four distinct purposes — and that mixing these purposes in a single document is the most common cause of confusing documentation. Understanding Diataxis also gives you a precise vocabulary for discussing documentation quality with your team.

The Four Types of Diataxis Documentation

Type	Answers the question	Serves	Is oriented toward
Tutorial	”How do I get started?”	A learner	Learning
How-to guide	”How do I accomplish a specific goal?”	A practitioner	A goal
Explanation	”Why does this work the way it does?”	Someone seeking understanding	Understanding
Reference	”What is the exact specification?”	A practitioner who needs facts	Information

Tutorials

A tutorial is a learning experience. The reader is a beginner who does not yet know enough to ask the right questions. Your job as the writer is to give them a successful, guided experience that builds confidence.

Key characteristics:

• Step-by-step, sequential structure
• Always results in a concrete outcome
• Explains only what is necessary for the task at hand — does not explain theory
• Assumes nothing about prior knowledge

Tutorial vocabulary:

• “In this tutorial, you will…”
• “By the end of this tutorial, you will have…”
• “Run the following command…”
• “You should see the following output…”
• “Congratulations — you have successfully…”

Common mistake: Turning a tutorial into a how-to guide by offering choices. A tutorial should make decisions for the learner.

How-To Guides

A how-to guide is a task-focused recipe. The reader is a practitioner who already knows the basics and wants to accomplish a specific goal. Unlike a tutorial, a how-to guide assumes existing knowledge and does not hand-hold.

Key characteristics:

• Focused on a specific, real-world goal
• Does not teach — it guides
• May acknowledge that there are multiple ways to achieve the goal
• Written for a reader who may already be partway through a task

How-to guide vocabulary:

• “To configure X, do the following:”
• “If you need to Y, use the following approach:”
• “This guide assumes you have already installed…”
• “For an explanation of why this works, see the [explanation document].”

Common mistake: Including explanatory background that the reader doesn’t need to accomplish the task. Put that in an explanation document instead.

Explanations

An explanation document provides conceptual understanding. It answers “why” and “how does this work” questions. The reader is not trying to accomplish a task right now — they want to understand.

Key characteristics:

• Discursive and exploratory in tone
• May use analogies and history
• Does not include step-by-step instructions
• May discuss trade-offs, design decisions, and alternatives

Explanation vocabulary:

• “The reason for this design is…”
• “Historically, this approach emerged from…”
• “Understanding X requires understanding Y first.”
• “There are three ways to think about this…”
• “The trade-off between X and Y means that…”

Example explanation opening: “Authentication in this system is stateless, which means the server does not store any session information. This section explains what that means, why it was designed this way, and what implications it has for how you use the API.”

Reference

Reference documentation provides factual information for lookup. It is the most structured type of documentation — the reader knows what they need and just wants the precise specification.

Key characteristics:

• Structured consistently so information is predictable to find
• Descriptive, not instructional
• No opinions or explanations — just facts
• Often auto-generated from code (e.g. API references, CLI help text)

Reference vocabulary:

• “Returns… / Accepts… / Requires…”
• “Type: string | integer | boolean”
• “Default: [value]”
• “See also: [related reference entries]”

Example reference entry: “max_retries (integer, optional, default: 3) — The maximum number of retry attempts for a failed request. Setting this to 0 disables retries.”

Using Diataxis in Practice

The most valuable use of Diataxis is as a diagnostic tool. When a document is confusing or unhelpful, ask: is it trying to be two things at once?

“This document starts as a tutorial, then switches to a reference in the middle — that’s why it’s hard to follow. Let’s split it.”

Team review questions:

• “Is this a tutorial or a how-to guide? If the reader already knows the basics, it’s a how-to guide.”
• “Should this explanation be in the tutorial, or does it interrupt the learning experience?”
• “Is this step-by-step content, or is it reference information? Reference belongs in a separate page.”

Example Sentences

1. “The onboarding documentation currently mixes tutorial content with reference material — new users are getting confused because they can’t tell what they need to do versus what they might need to look up.”
2. “A how-to guide for this task is more appropriate than a tutorial — our users already understand the fundamentals and just need a clear recipe for the specific scenario.”
3. “The explanation document for the authorisation model should describe the design decisions and trade-offs, not the steps to configure it — that belongs in the how-to guide.”
4. “Reference documentation for the CLI should be auto-generated from the code to ensure it stays accurate — manually maintained reference pages tend to drift.”
5. “Applying the Diataxis framework to our documentation audit helped us identify that we had 40 tutorial-style documents but almost no explanations — which is why users understood how to get started but struggled to understand why things worked the way they did.”