Here’s a familiar scenario: a user lands on a documentation page that starts with a tutorial-style introduction, then stops mid-task to explain the architecture, then adds a configuration reference table, and then wraps up with some conceptual notes on why the system works the way it does. The page tries to be everything at once, and succeeds at being nothing in particular. The beginner doesn’t know what to skip. The expert can’t find the table without reading around it. Everyone leaves mildly frustrated.
This problem has a name and a solution. Daniele Procida developed the Diataxis framework as a way of organizing documentation into four distinct types, each serving a different user need. The framework has been adopted by Canonical (Ubuntu), Cloudflare, Gatsby, and others.
The four types are tutorials, how-to guides, reference, and explanation.
A tutorial is learning-oriented. It takes the user through a task step by step, in a controlled environment, for the purpose of learning by doing. The user follows along and builds something. The tutorial’s job is to give the learner a successful experience, not to explain everything — there will be time for that later. A tutorial that stops to explain theory loses the learner. They came to do, not to read.
A how-to guide is problem-oriented. It assumes the user already knows the basics and has a specific goal: “How do I connect to a remote database?” or “How do I set up authentication?” A how-to guide doesn’t teach; it shows the steps for accomplishing something. It assumes knowledge and gets to the point.
Reference is information-oriented. It’s the API docs, the configuration parameter list, the command-line flags. It doesn’t tell a story. It answers “what does this do?” with precision and completeness. Adding narrative to a reference page slows down the user who arrived there for a specific fact.
Explanation is understanding-oriented. It explores why. Why does the system work this way? What are the trade-offs of this design? What would happen if we approached this differently? Explanation doesn’t lead to a specific action; it builds the mental model that makes future actions more informed.
The key insight of Diataxis is not that these four types exist. Most people already sense that distinction. The insight is that mixing types in a single document is what makes documentation confusing. A reference page that starts with a paragraph of motivational context wastes the expert’s time. A tutorial that adds reference material pulls the learner out of the task. The problem isn’t bad writing; it’s the wrong type of content for the user’s current need.
If you want to compare Diataxis against DITA and other structured approaches, idratherbewriting.com has a useful analysis. The conclusion: Diataxis travels well because it’s principle-based rather than tool-based. You can apply it in any format, any authoring tool, any content management system.
The framework doesn’t tell you what to write. It tells you what role each piece of documentation is playing. That clarity alone fixes a surprising number of problems.