The Diataxis Framework Explained: Four Types of Documentation
Understand the Diataxis framework for technical documentation — tutorials, how-to guides, explanations, and reference — with vocabulary and example sentences for documentation engineers.
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
- “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.”
- “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.”
- “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.”
- “Reference documentation for the CLI should be auto-generated from the code to ensure it stays accurate — manually maintained reference pages tend to drift.”
- “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.”
Navigating Nuances: Targeted Language for International Teams
The Diataxis framework – breaking down documentation into tutorials, how-to guides, explanations, and references – is a solid foundation. But let’s be honest, effective technical communication isn’t just about the structure; it’s profoundly shaped by language. For developers who are building their professional English skills, particularly those coming from backgrounds where technical vocabulary might differ significantly, the subtleties of phrasing can make all the difference between clear understanding and frustrating misinterpretations.
Consider this common scenario: a developer, let’s call him Jian, submits a pull request to update the authentication flow in our application. The PR description reads simply, “Fixed authentication bug.” While technically accurate, it’s incredibly vague. A native English speaker would immediately understand the context and scope of the change. But for someone still developing their professional vocabulary, this could lead to questions like, “What specific bug was fixed? What were the steps taken to resolve it?” The lack of detail creates ambiguity and demands clarification – potentially slowing down the review process.
Similarly, during a code review, you might receive a comment from Sarah: “This section needs more context.” Without understanding what ‘context’ means in this technical environment, Jian could feel immediately criticized or unsure how to proceed. It’s crucial to remember that “more context” doesn’t always mean adding layers of jargon; it frequently asks for a clear explanation of why a particular decision was made and its impact on the overall system. Phrases like “This modification improves performance by X%” are immediately understandable, while simply stating “Optimized code” leaves room for confusion and requires further investigation.
Focusing on precision in your descriptions is key. Instead of saying “Implemented error handling,” try something more specific: “Added robust error handling to the API endpoint, including logging detailed exception information and implementing a retry mechanism with exponential backoff.” This level of detail demonstrates professionalism and proactively addresses potential questions. Remember, building a strong technical vocabulary isn’t just about learning new words; it’s about understanding how those words are used within a specific professional context – one where clarity and unambiguous communication are paramount to successful collaboration. Don’t be afraid to ask for clarification if you’re unsure of a term or phrase, and always strive to articulate your thought process clearly and precisely.