Language & documentation · Framework
Diátaxis
Choose documentation around whether someone is learning or working, and doing or understanding.
What it helps you do
Give a document a coherent job rather than mixing learning, task completion, lookup, and conceptual discussion indiscriminately.
Starting knowledge: No specialist knowledge is required.
- A tutorial guides a learner through a successful learning experience.
- A how-to guide helps someone with enough background complete a specific task.
- Reference supports precise lookup; explanation develops context and understanding.
The problem it came from
Daniele Procida developed Diátaxis as an approach to technical documentation. Its four forms distinguish tutorials, how-to guides, reference, and explanation.
The framework builds a map from reader needs. It is not a file format, a writing standard, or a requirement to make four equally sized sections.
Work through an example
Tutorial: build a small working example with guidance.
How-to: change an existing configuration.
Reference: look up flags and defaults.
Explanation: understand why the configuration exists.- The same subject can have four different reader jobs.
- The tutorial may link to reference without reproducing every option.
- The explanation can remain useful after the commands change.
Where it helps. Where it stops.
Use it when
- Planning a documentation collection or repairing a page that tries to do everything.
- Deciding what an AI-generated answer should accomplish for its reader.
Potential benefits
- Naming the reader need helps authors select the right content.
- Links between forms allow depth without interrupting the immediate task.
Limits and common mistakes
- The categories guide judgment; they do not automatically classify every sentence.
- Clear organization cannot compensate for incorrect examples or missing prerequisites.
The prompt below asks for this structure. It does not guarantee accuracy, complete coverage, better learning, or conformance to a standard. Treat those outcomes as separate checks.
Practise the judgment
Try a choice, inspect a boundary, then explain a case yourself. Hints and answers are available whenever you need them.
An experienced user needs the exact timeout option and its default. Which form fits?
Hint
They already know what they want to change.
Explained answer
Best answer for this case: Reference
The reader is applying existing knowledge and needs precise lookup information.
A new learner follows a safe exercise to build a first working example. Which form fits?
Hint
Look for acquisition of skill through action.
Explained answer
Best answer for this case: Tutorial
A tutorial structures a learning experience rather than simply listing production steps.
Split a page that mixes “why backups matter,” first-time practice, and command flags.
Hint
Different parts may answer different questions.
Explained answer & self-review rubric
Create an explanation for rationale, a tutorial for the first practice backup, and reference for flags. Add a how-to when a recurring operational task needs its own route.
- Identify reader needs
- Assign distinct jobs
- Link the forms together
Take it into your own work
Manual template
Use this structure yourself, with a colleague, or in your preferred writing tool.
# Documentation brief
Reader:
Learning or working?
Doing or understanding?
Chosen form:
Prerequisites:
Outcome:
Content needed for this form:
Related forms to link:
Review the result
- Is the reader learning or applying existing skill?
- Does the page support action or understanding?
- Have useful details been linked rather than deleted?
Use this approach with your own AI tool
Help me apply Diátaxis to the material below.
Reader and existing knowledge: [describe]
Task and desired outcome: [describe]
Use these principles: A tutorial guides a learner through a successful learning experience.; A how-to guide helps someone with enough background complete a specific task.; Reference supports precise lookup; explanation develops context and understanding..
Preserve source facts, identifiers, quantities, conditions, exceptions, and uncertainty.
Separate supplied facts from assumptions. Ask for missing information instead of inventing it.
Explain your representation choices and provide a review checklist. Do not claim formal compliance or correctness from formatting alone.
Material: [paste only information you are permitted to share]Go to the source
History and the underlying approach are grounded in these references. Examples, prompts, and practice cases here are original educational adaptations. Edition-specific details should be checked against the referenced publication.
Last editorial review: 2026-10-24. An overview is not certification, and this guide is not a reproduction of a standard.