Diátaxis is the best thing to happen to technical writing in a decade. It is also, quietly, one of the hardest frameworks to retrofit onto a doc set that has to be read by a retriever as well as a human.

This post says the thing most AI-docs content avoids saying out loud: the canonical framework of our field has seams, and those seams are exactly where language models stumble. We wrote it as practitioners who use Diátaxis every week, not as contrarians looking for a new slogan. The argument is extend, not replace.

The framework, on its own terms#

Daniele Procida's Diátaxis sorts every documentation page into one of four modes along two axes. One axis runs from practical steps (action) to theoretical knowledge (cognition). The other runs from study (acquisition of skill) to work (application of skill). Cross them and you get four quadrants, each with a different job:

Tutorials are learning-oriented. Action plus acquisition. A guided first encounter in which the reader follows a trusted hand through a working example and comes out with new skill.
How-to guides are task-oriented. Action plus application. The reader already has skill; they need to accomplish a specific goal and want the shortest honest path to the outcome.
Reference is information-oriented. Cognition plus application. The reader is at work and needs a fact: a parameter, a return value, a status code. Reference describes the machinery accurately and gets out of the way.
Explanation is understanding-oriented. Cognition plus acquisition. The reader steps back from the keyboard to ask why the system is shaped the way it is. Explanation connects pieces and gives the reader a mental model.

The framework's insight is that these four modes serve different reader needs and should not be mixed on a single page. A tutorial that keeps pausing to explain architecture stops being a tutorial. A reference page that narrates a journey stops being reference. Procida's rule is to write each page as one thing, and let the shape of the doc set emerge from that discipline.

What Diátaxis gets right#

Diátaxis gave writers a decision rule, and decision rules are rare in our field. "Is this a tutorial or a how-to?" is an answerable question once you know the axes. That answerability alone drained the pile of shapeless, purpose-unclear pages that lived on every doc site a decade ago. Serious doc sets published after 2018 are measurably better because of Procida's work, and the improvement is visible to anyone who has migrated an old wiki.

The framework also gave readers a mental map. Users learn where to look for what. Navigation gets cleaner. New contributors understand where a page belongs before they write it, which means the doc set stops drifting the moment the original author leaves. Teams that adopt Diátaxis usually find that their arguments about documentation shift from "what should this page be" to "are we doing the four modes well," which is a healthier argument to have.

We use it. We recommend it. The critique that follows is meant as the kind of engagement a framework earns when it becomes canon.

Where it strains under retrieval#

A retriever is not a user with a mental map. It is a ranking function over chunks of text, scoring them by similarity to a query and handing the top-k to a model. It does not know your information architecture. It does not read your sidebar. It does not care that a page is labeled "Explanation" or "How-to." It sees tokens and cosine distance.

That difference produces three specific tensions with Diátaxis as written.

Task context is spread across quadrants#

A real user question rarely lives in one quadrant. Consider: "How do I set up webhooks with signature verification for a Stripe-like payment flow?" The procedure sits in a how-to. The endpoint and header shapes sit in reference. The reason signature verification matters — replay attacks, shared secrets, clock skew — sits in explanation. A human reading the doc site composes the answer by moving across pages. They use the sidebar, they open a second tab, they skim the concept page when something surprises them.

The retriever does none of that. It pulls the top-ranked chunk from one page and calls it done. If that chunk is the how-to, the model generates a procedure with no mention of why verification matters and produces confident code that fails closed on a malformed header. If the chunk is the explanation, the model gives the user a thoughtful essay when they asked for curl.

Diátaxis tells the writer to separate these modes, and for a human reader that separation is correct. The retriever punishes it. The seam between quadrants is exactly where task context gets lost.

Explanation is where drift hides#

Conceptual pages — the explanation quadrant — are the least visited, the least edited, and the most confidently wrong part of most doc sets. Users do not flag them, because users do not read them. The team does not notice, because the analytics are quiet. So the concept page that described the auth model in 2022 still describes it today, even though the auth model changed twice.

Humans mostly survive this. They skip explanation pages or read them once and forget them. Retrievers do not skip. When a user asks an LLM-powered assistant "why does our system do X," the retriever walks straight into the stalest part of the doc set and pulls the most authoritative-sounding paragraph it can find. The model cites it. The user believes it. The staleness surfaces as an answer, not a 404.

Diátaxis encourages treating explanation as a distinct body of work with its own rhythm. That distinctness is a feature for writing and a liability for currency. The quadrant that gets the least maintenance attention is the one a retriever will happily quote.

Tutorials and how-tos collide in vector space#

To a human, a tutorial and a how-to feel obviously different. One is a guided walk; the other is a pointed task. To a retriever, both are procedural prose with numbered steps, imperative verbs, and code blocks. They embed close together. They share vocabulary. When a user asks "how do I add a webhook," the retriever often returns whichever is longer and more term-dense, which is usually the tutorial.

The concrete failure: a developer asks an assistant for the three-line how-to on rotating an API key. The retriever surfaces the "Getting Started with API Keys" tutorial, which opens with account setup, walks through creating a first key, and only touches rotation in step nine. The model, trying to be faithful to its sources, hands the developer twelve steps of onboarding they did not ask for. The tutorial was not wrong. It was the wrong shape for the query, and the retriever had no way to tell.

Adjustments, not replacement#

Three changes keep Diátaxis intact for humans and make it friendlier to retrievers. None of them require the author to abandon the four modes; they sit on top of the framework, not in place of it.

Cross-quadrant task pages#

Keep the four quadrants as an authoring model. Add a fifth artifact — the task page — that composes across them. One page per real user intent, pulling the procedure, the reference it depends on, and the concept that makes the procedure safe into a single retrievable object. A task page is not a new quadrant. It is a projection: the same material, rearranged for a reader whose context is a query rather than a sidebar.

Task pages should be named after the intent, carry a short rationale paragraph up top, embed the minimal reference inline, and link out to the canonical tutorial, how-to, reference, and explanation for readers who want the full trail. Retrievers love them because task context stops being distributed. Humans do not mind them because they read like the page they were trying to assemble anyway.

Currency owed to explanation#

The explanation quadrant needs a review cadence it rarely gets. Every conceptual page should carry a last-reviewed date, a named owner, and a quarterly currency check on the calendar. Not because humans are complaining — they are not — but because a retriever will cite these pages the moment an assistant comes online, and a citation inherits the authority of the source.

The cadence does not have to be heavy. A fifteen-minute quarterly pass by the owning engineer, with a visible date stamp, is enough to catch the drift that matters. The point is to treat explanation the way we already treat reference: as a surface with a contract.

Disambiguated titles#

"Getting Started" and "Setting Up Your First Webhook" should not live in the same page inventory under similar names. Titles are the strongest single signal a retriever has, and generic titles collide with everything. The rule we use: task pages get titled after the task in the user's words, tutorials get titled as tutorials ("Tutorial: Your First Webhook"), and reference pages get titled after the thing they describe. Disambiguation helps the retriever rank correctly and costs the human reader nothing.

What this means for writers#

Not much, in practice. If you are using Diátaxis well, you are most of the way there. The remaining work is the task-page projection layer and the review cadence on explanation. If you are using Diátaxis badly — a "tutorials" folder holding forty pages that are actually how-tos, or an explanation section no one has touched since the last rebrand — the framework is not what is failing you, and no retrieval adjustment will save a doc set that has not done the primary work.

The honest version of the claim is this. Diátaxis is right about how humans read. Retrieval is a second reader with different habits, and a good doc set now serves both. The four modes remain the authoring discipline. The task page is the retrieval surface. The review cadence is the insurance policy on the quadrant that used to get away with neglect.

Closing#

The point of engaging the canon is not to break with it. We show up as participants in the field, not outsiders with a rival diagram. If you have read Procida, read this as a continuation: the framework was built for a reader who navigates by intent, and we are adding an adjacent reader who navigates by tokens. If you have not read Procida, read him first. The adjustments only make sense on top of the foundation he laid, and the foundation is still the part that does most of the work.