The 4 Types of Documentation: Diátaxis Framework Explained

If you have ever rewritten the same documentation three times and it still felt wrong, you probably had a documentation type problem — not a writing problem.

The Diátaxis framework (created by Daniele Procida) solves this by dividing all technical documentation into four distinct types. Each type serves a different user need, has a different structure, and uses different language. Mixing types is the most common cause of confusing documentation.

Understanding Diátaxis makes you a significantly better technical writer — and helps you review, structure, and commission documentation more effectively.

---

The Four Types at a Glance

Type	User’s goal	Analogy
Tutorial	Learning	A cooking class
How-to Guide	Doing a specific task	A recipe
Reference	Checking a fact	A dictionary definition
Explanation	Understanding a concept	An essay

The framework maps these on two axes:

• Practical vs theoretical (tutorials/how-to guides vs reference/explanation)
• Study vs work (tutorials/explanation vs how-to guides/reference)

---

Type 1: Tutorial

What it is

A tutorial is a learning experience. It takes an absolute beginner through a complete, working experience — not a comprehensive one.

The goal of a tutorial is not to build something useful. The goal is to give the reader a successful first experience with a tool or technology.

When to use it

• A user is completely new to your product
• You want to reduce the barrier to getting started
• You want to establish confidence before complexity

What it is NOT

• A how-to guide (tutorials don’t solve real user problems)
• A reference (tutorials don’t document everything)
• An explanation of why things work the way they do

Structure

1. Start with a concrete outcome — what will the user have built by the end?
2. Do the work for them — minimal choices, specific instructions
3. Explain the minimum needed — don’t explain internals during the learning experience
4. Ensure it works — a tutorial that fails is worse than no tutorial

Language

• Present tense, second person, active voice
• Imperative verbs: “Create a file. Run the command. Navigate to…”
• Short sentences, one action per sentence
• Reassure: “You should now see… If you see an error, check…”

Example: Getting Started with the CLI

# Getting Started with the Acme CLI

By the end of this tutorial, you will have:
- Installed the Acme CLI
- Created your first project
- Deployed it to staging

This takes about 15 minutes.

## Step 1: Install the CLI

Run the following command in your terminal:

npm install -g acme-cli

You should see output like this:
+ acme-cli@2.1.0 added

## Step 2: Create a project

acme create my-first-project

When prompted, select the "basic" template.

Navigate into your new project directory:

cd my-first-project

You now have a working project. Let's deploy it.

---

Type 2: How-To Guide

What it is

A how-to guide is a series of steps that accomplishes a specific goal. Unlike a tutorial, the user knows what they want to do — they just need the steps to do it.

“How do I set up authentication?” “How do I deploy to production?” “How do I configure environment variables?”

When to use it

• The user has a concrete goal to accomplish right now
• They are not starting from zero — they have context
• The task has a defined beginning and end

What it is NOT

• A tutorial (it assumes experience, not providing it)
• A reference (it doesn’t exhaustively document options)
• An explanation (it doesn’t explain why — only how)

Structure

1. Title states the goal: “How to Configure SSL Certificates”
2. Prerequisites (brief): what the user needs before starting
3. Steps: numbered, imperative, specific
4. Result: what success looks like

Language

• Imperative verbs (same as tutorials)
• Minimal explanation of why — the reader is in task mode
• If a step seems surprising, one sentence of context is acceptable
• Assume competence: skip basic explanations your audience already knows

Example: How to Roll Back a Deployment

# How to Roll Back a Kubernetes Deployment

**Prerequisites:** kubectl configured with cluster access, deployment name

## Steps

1. Check the rollout history to identify the target revision:
   kubectl rollout history deployment/my-service

2. Roll back to the previous revision:
   kubectl rollout undo deployment/my-service

   To roll back to a specific revision:
   kubectl rollout undo deployment/my-service --to-revision=3

3. Verify the rollback is complete:
   kubectl rollout status deployment/my-service

   You should see: "successfully rolled out"

4. Confirm the correct version is running:
   kubectl describe deployment/my-service | grep Image

---

Type 3: Reference

What it is

Reference documentation is neutral, factual, complete information about the subject. It is what the user consults when they need to know something specific — a parameter name, a return type, a default value.

When to use it

• Documenting an API, CLI, configuration file, or data schema
• Providing a complete list of options, parameters, or values
• Creating material that engineers will search while working

What it is NOT

• A tutorial (it doesn’t guide, it informs)
• A how-to guide (it doesn’t provide steps)
• An explanation (it doesn’t provide context or rationale — just facts)

Structure

• Consistent format (often a table or structured list)
• Complete coverage (all parameters, all edge cases)
• No narrative — just facts

Language

• Declarative, not imperative
• Present tense: “Returns the user object. Accepts two arguments.”
• No subjective language: not “This is a useful parameter” — just state what it does

Example: API Endpoint Reference

## POST /users

Creates a new user account.

### Request body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| email | string | Yes | Must be a valid email address. Maximum 254 characters. |
| password | string | Yes | Minimum 8 characters. |
| name | string | No | Display name. Maximum 100 characters. Defaults to email prefix. |
| role | enum | No | `user` or `admin`. Defaults to `user`. |

### Response

**201 Created**
Returns the created user object.

**400 Bad Request**
Returned when required fields are missing or fields fail validation.

**409 Conflict**
Returned when the email address is already registered.

---

Type 4: Explanation

What it is

Explanation (or “discussion”) provides background understanding. It answers why and how it works, not how to use it. It is the most neglected type of technical documentation.

When to use it

• Explaining the design decisions behind an architecture
• Providing context for why a tool works the way it does
• Covering trade-offs, limitations, and alternatives
• Writing an ADR (Architecture Decision Record)

What it is NOT

• A tutorial (it doesn’t guide action)
• A how-to guide (it doesn’t help you do a task right now)
• A reference (it doesn’t list facts)

Structure

• Can be free-form, essay-style
• Uses section headings for navigation
• Can include diagrams, comparisons, trade-off tables

Language

• Discursive and exploratory
• “This is because…”, “The reason we chose…”, “A common alternative is…”
• First person plural is acceptable: “We decided to…”
• Can include uncertainty: “This approach works well for X but struggles with Y.”

Example: Why We Use Event Sourcing

## Why We Use Event Sourcing in the Orders Service

The orders service stores all state changes as an immutable event log 
rather than updating records in place. This section explains the reasoning 
behind this choice and the trade-offs involved.

### The problem with mutable state

Traditional CRUD systems store only the current state of an entity. When 
an order changes from "pending" to "paid", the database record is updated. 
This means the history of how an order reached its current state is lost.

For financial transactions and audit requirements, this creates problems...

### Why event sourcing fits our context

Orders are naturally a sequence of events: created, payment initiated, 
payment confirmed, warehouse notified, shipped, delivered...

### Trade-offs

Event sourcing requires an event store, adds complexity to reads (projection 
required), and makes debugging more involved. These costs are justified for 
orders because...

---

The Most Common Documentation Mistake

The most common documentation problem is mixing types in a single document. This creates documents that are unclear because they serve multiple purposes simultaneously.

Classic mixed-type examples:

1. Tutorial with reference interjected — “Run npm install. The --save flag adds the package to package.json. Note: npm also supports --save-dev for development dependencies. The --no-optional flag skips optional dependencies. You can also use yarn add.” → The tutorial has derailed into reference documentation. The reader is learning but is now overwhelmed with options.

2. How-to guide with explanation mixed in — “Click Deploy. The deployment process works by containerising the application using Docker, which was chosen over Podman because of its widespread adoption. The container is then pushed to ECR. Click Deploy.” → The reader wants to deploy, not read an essay on Docker.

3. Reference that tries to be a tutorial — API documentation that walks you through a complete scenario instead of listing parameters neutrally.

Fix: Before writing any section, ask: “Which type of documentation is this?” If it’s a tutorial, remove the reference content. If it’s a how-to guide, remove the explanations. Write each type separately and link between them.

---

Quick Identification Test

When you are not sure which type you need, ask these questions:

1. Is the reader learning or doing? → Learning = tutorial/explanation, Doing = how-to/reference
2. Does the reader need steps or facts? → Steps = tutorial/how-to, Facts = reference
3. Is the reader a beginner or experienced? → Beginner = tutorial, Experienced = how-to/reference
4. Does the document need a narrative? → Yes = tutorial/explanation, No = how-to/reference

---

Using Diátaxis in Practice

When structuring a documentation site:

• Getting Started → Tutorial (one complete flow)
• Guides / How-To → How-to guides (task-based, searchable by goal)
• API Reference → Reference (complete, consistent, navigable)
• Concepts / Architecture → Explanation (deep background)

This maps to nearly every successful developer documentation site: Stripe Docs, Kubernetes Docs, Django Docs, AWS Documentation.

---

Related Resources

• Modal Verbs in Technical Writing
• Active vs. Passive Voice in Technical Writing
• Writing API Documentation in English