Documentation Frameworks: A Field Guide
Diátaxis is the one to start with, but DITA, minimalism, and others fill the gaps it leaves open.
Most documentation has a structural problem that exists before any individual piece of writing: nobody has decided what kind of content belongs in the documentation and what each content type is supposed to do.
The result is documentation that mixes procedures, explanations, reference material, and tutorials in ways that make all four harder to use. A procedure buries a conceptual explanation in step three. A tutorial drifts into reference documentation halfway through. A user looking for a specific parameter value has to read through four contextual paragraphs to find it.
The Diátaxis framework, developed by Daniele Procida, gives technical writers a clear vocabulary for solving this problem. It’s the most useful structural model I’ve encountered in my years in documentation.
The Four Content Types
Diátaxis proposes that all technical documentation falls into one of four categories, distinguished by two axes: acquisition vs. application (is the user studying the craft, or working in it?) and action vs. cognition (does the content inform what they do, or what they think?).
Tutorials are learning-oriented and practical. They guide a user through a complete, realistic experience — not to accomplish a real task, but to develop capability and confidence. A tutorial says “let’s build something together.” The user’s goal is learning how to work with the product. The documentation’s goal is ensuring that learning happens systematically.
How-to guides are task-oriented and practical. They assume the user has a specific goal and prior capability. A how-to guide says “here’s how to do this specific thing.” It doesn’t explain why; it delivers the steps. In the doc sets I’ve worked on, this is the most common type of content, and it’s the one most likely to be contaminated with explanation that belongs elsewhere.
Reference is task-oriented and theoretical, consulted while working but about facts rather than actions. It’s the complete, authoritative record of what the system does — all the endpoints, all the parameters, all the options. Reference documentation is looked up, not read. It should be comprehensive, precise, and free of narrative.
Explanation (or “discussion”) is learning-oriented and theoretical. It addresses the question “why?” Why the system works this way, what the design tradeoffs were, and what the underlying concepts mean. Explanation is read when a user wants to deepen understanding, not when they’re in the middle of a task.
Mixing Types Creates Problems
Each content type serves a different user need. When types are mixed, documents fail to serve any of them well.
A how-to guide that explains the underlying architecture is a problem for the user who just needs to complete a task. They don’t want or need to read through the explanation to find the steps. A tutorial that turns into a reference document fails as a tutorial because reference material isn’t how you develop capability.
The most common mixing problem is explanation contaminating how-to guides. Writers know why a step is necessary and can’t resist explaining it. You might think it is helpful. The result is a procedure that takes three times as long to read as it should.
The fix is to move the explanation to its own document and link to it from the how-to guide. Users who need the context can find it. Users who just need the steps don’t have to read it.
Mapping Existing Docs to the Framework
If you have existing documentation, a Diátaxis audit is worth the time. Go through your docs and, for each page, ask: what is this content actually for? Mark each page as tutorial, how-to, reference, or explanation.
You’ll almost certainly find pages that span two or three categories. Those are the candidates for splitting. You’ll also find categories that are missing entirely. Many teams have reference and how-to material but no explanations, which means users with conceptual questions have nowhere to go.
The audit also reveals whether your site navigation reflects the content structure. If your navigation groups content by product feature rather than by content type, users are probably struggling to find what they need because the site is organized around what the product does, not around what users are trying to do.
The “Getting Started” Problem
One content type that trips up Diátaxis audits: onboarding or “getting started” content. These pages often try to be everything simultaneously. They want to give you enough context to understand the product, enough instruction to complete a first task, and enough reference to know what options exist. The result is a page that does none of those jobs completely.
The Diátaxis-aligned approach is to split getting started into a tutorial (building something small end-to-end, focused on learning) and a quickstart how-to (the fastest path to a working setup, focused on doing). They serve different users: someone exploring the product for the first time versus someone who’s decided to use it and needs to get configured quickly.
Diátaxis Isn’t the Only Map
Diátaxis is the framework I reach for first, but it isn’t the only one, and it doesn’t claim to cover everything. It sorts content by purpose. It says nothing about how tightly to write each page, or how to structure the topic once you know what type it is. Four other frameworks fill gaps Diátaxis leaves open, and a couple of them predate it by decades.
DITA (Darwin Information Typing Architecture) came out of IBM and became an OASIS standard in 2005. It’s topic-based authoring taken to its structural conclusion: content is written as standalone topics, each typed as concept, task, or reference, then assembled into deliverables with maps. If those three types sound familiar, they should. DITA’s concept/task/reference maps almost directly onto Diátaxis’s explanation/how-to/reference, minus the tutorial. The difference is scope. Diátaxis is a way of thinking about content. DITA is a full XML architecture with tooling, content reuse, and conditional publishing behind it. Most teams don’t need DITA’s machinery. But if you’re publishing the same content across many products and outputs, the reuse model is the reason DITA still runs large documentation sets.
Information Mapping, developed by Robert Horn in the 1960s, is one level down from Diátaxis. Where Diátaxis types the page, Information Mapping types the individual chunk of information inside it: procedure, process, principle, concept, structure, and fact, and insists each chunk be labeled and kept separate. It’s stricter and more granular than most writers want day to day, but the core discipline is worth stealing: name what each block of content is before you write it, and don’t let a fact and a procedure share a paragraph. That’s the same instinct Diátaxis applies to whole pages.
The style frameworks solve a different problem. Diátaxis tells you a how-to guide should contain steps and nothing else. It doesn’t tell you how to write the steps. Minimalism, from John Carroll’s 1990 book The Nurnberg Funnel, does: get the user acting immediately, cut the throat-clearing preamble, support error recovery instead of trying to prevent every error with warnings. Minimalism is why a good quickstart drops you into a real task on line one instead of explaining the product first. It pairs naturally with the how-to and tutorial quadrants.
Every Page Is Page One, from Mark Baker’s 2013 book, is the framework for how people actually arrive at docs: through search, landing mid-site on a single page with no memory of the pages before it. Each topic has to stand on its own — establish its context, state its scope, link to what it assumes — because you can’t count on the reader having read anything else first. This is the assumption Diátaxis shares but never says right out. If your docs are read start-to-finish like a book, you can be looser. If they’re found through search, every page carries the whole burden of orienting the reader. That’s a problem of arrangement, not content type, and we’ll see it in the upcoming article on information architecture.
None of these replaces Diátaxis. DITA and Information Mapping give you sharper structural tools; minimalism and Every Page Is Page One govern how the writing behaves once the structure is set. The useful move is to treat Diátaxis as the top-level sort and pull the others in where they do work that Diátaxis doesn’t.
A Caveat
Diátaxis is a strong default, not a mandate that every documentation set must have exactly four folders. Small documentation sets — a single-purpose CLI tool with a handful of commands — can be over-served by four separate content types when a few well-organized pages would do. The framework’s value is the discipline of asking, for any given piece of content, “who is reading this and what are they trying to do right now?” If a small site answers that question clearly without formally adopting all four categories, it doesn’t need to force the split for the sake of following the model precisely.
Further Reading
Daniele Procida, Diátaxis framework documentation at diataxis.fr — the primary source, actively maintained, free.
OASIS DITA specification at docs.oasis-open.org/dita — the standard itself, for teams weighing topic-based authoring and content reuse.
Robert E. Horn on Information Mapping — background at informationmapping.com — the method for typing and labeling information at the chunk level.
Tom Johnson, What is Diátaxis and should you be using it with your documentation? — a longer comparison of Diátaxis against DITA, Information Mapping, and the Good Docs Project.
John M. Carroll, The Nurnberg Funnel: Designing Minimalist Instruction for Practical Computer Skill (MIT Press, 1990) — the founding text on minimalism in technical instruction.
See his other work, Minimalism Beyond the Nurnberg Funnel.Mark Baker, Every Page Is Page One: Topic-Based Writing for Technical Communication and the Web (XML Press, 2013) — writing for readers who arrive by search.
Google’s Technical Writing courses at developers.google.com/tech-writing — free companion courses on clear technical prose, taken by Google’s own engineers.
What You Can Do
Pick three pages from your documentation (or any public documentation you have access to).
Classify each one: tutorial, how-to, reference, or explanation. Then identify whether each page stays in its lane or mixes types.
Next: Stop the Sprawl: Information Architecture — once you know what types of content you have, you have to organize them. Here’s more on how to structure documentation so users can find what they need.