Diátaxis splits documentation into four types, already adopted by Cloudflare and Gatsby

Diátaxis is a framework for thinking about and writing technical documentation. Its core claim is that documentation readers have four distinct needs, and that each need corresponds to its own form of content: tutorials, how-to guides, technical reference and explanation. Diátaxis places these four forms in a systematic relationship to one another and argues that documentation should be organised around that structure rather than grown ad hoc. The framework positions itself as covering three separate problems at once: what to write (content), how to write it (style) and how to arrange it (architecture). Its own site describes it as light-weight, easy to grasp and straightforward to apply, and says it imposes no implementation constraints, meaning it does not dictate what tools or publishing system a team uses. The site also states that its principles have been adopted successfully in hundreds of documentation projects, though it does not name those projects or give a precise count. Three endorsements accompany the framework. Greg Frileux of Vonage says Diátaxis let the company build a high-quality set of internal documentation that both users and contributors like adding to. A company statement from Gatsby says the team used Diátaxis as its go-to resource while reorganising its open-source documentation, with the four categories helping it prioritise the reader's goal for each type of content and making it easier for users to find what they needed. A company statement from Cloudflare says Diátaxis became the team's north star for information architecture while redesigning Cloudflare's developer docs, and that the documentation is now clearer than ever for both readers and contributors. The framework's own site does not name individual authors for the Gatsby or Cloudflare testimonials, and gives no date for when Diátaxis was created or when any of the testimonials were written.

Key facts

Diátaxis identifies four distinct documentation needs and matches each to its own form: tutorials, how-to guides, technical reference and explanation.
The framework addresses three separate problems in one system: what documentation should contain, how it should be written, and how it should be organised.
Vonage's Greg Frileux says Diátaxis let the company build high-quality internal documentation that both users and contributors like working on.
Gatsby says it used the four Diátaxis categories as its go-to resource while reorganising its open-source documentation, prioritising each reader's goal.
Cloudflare says Diátaxis became its north star for information architecture while redesigning its developer docs, which it says are now clearer for both readers and contributors.

Why it matters

Documentation inside most engineering teams grows without a plan: pages accumulate around whatever a contributor happened to be doing at the time, and readers with different needs are left to sort through the same undifferentiated pile. Diátaxis proposes a fix at the structural level rather than the sentence level: split content by what the reader is trying to do (learn, accomplish a task, look something up, or understand a concept) and give each of those four needs its own dedicated form. The framework frames this as solving three problems together, what to write, how to write it, and how to arrange it, rather than treating them as separate concerns.

Who it affects

The framework is aimed at documentation authors and maintainers rather than end users directly: technical writers, open-source maintainers and developer-relations teams who decide how a project's docs are structured. The three cited adopters, Vonage, Gatsby and Cloudflare, are all organisations with substantial developer-facing documentation, suggesting the framework's natural audience is teams writing for other engineers.

How to use it

Diátaxis describes itself as light-weight and straightforward to apply, and its site recommends starting with a brief primer before applying the framework directly. It does not impose implementation constraints, meaning teams can adopt the four-way split without committing to a particular publishing tool or platform. Gatsby's account describes a practical use pattern: using the four categories to decide, for each piece of content, which reader goal it should serve, then reorganising an existing documentation set around that decision.

How solid is it

The evidence for adoption comes entirely from the framework's own site: three testimonials, one from a named individual (Greg Frileux at Vonage) and two attributed only to companies (Gatsby and Cloudflare) with no individual named. The site's claim that its principles have been adopted in "hundreds of documentation projects" carries no supporting count, list of projects, or citation. There is no independent audit or third-party survey behind the framework's claims in this text, and no date is given for when Diátaxis was created or when the testimonials were collected.

Risks and caveats

The strongest available evidence is curated self-selection: three success stories chosen and published by the framework's own site are not the same as an independent measurement of how well Diátaxis works across the broader population of teams that have tried it. Two of the three testimonials name only a company, not an individual, which makes them harder to verify directly. The source text also does not name Diátaxis's creator or maintainer, so readers cannot judge the framework's track record or how long it has been in active use from this text alone.

“Diátaxis has allowed us to build a high-quality set of internal documentation that our users love, and our contributors love adding to.”

— Greg Frileux, Vonage