Trigpoint
Collections › Personal Knowledge Management › Diátaxis
“One document covering everything is fine”: it is not that simple.

Diátaxis

Diátaxis · Procida
Checked against the sources ✓ Personal knowledge management · documentation Tell the editor privately ▸
In three sentences Documentation usually fails for structural reasons rather than stylistic ones: four different reader needs get pushed into one document. Diátaxis separates them along two axes, whether the reader is doing or thinking and whether they are learning or working, producing four types: tutorial, how-to, reference and explanation. The core claim is that each type has its own job and the kinds of writing should not bleed into each other. The framework does not prescribe an implementation; whether to split them into separate files is the user's own choice.

↳ Seen a counter-example?

Two axes, four kinds of writing kept apart Procida (diataxis.fr) Study (learning) ←→ Work (applying) tutorial guided practice while learning how-to guide steps to a goal while working explanation understanding while learning reference information while working Practice (doing) Cognition (thinking) each type serves one reader need with its own rules (paraphrase: one passage should not serve two) The four names are verbatim from the primary site; this layout is indicative, not the site's own diagram. Figure: trigpoint.pub
Figure 1 · Two axes producing four types: practice against cognition, doing or thinking, crossed with learning against application, studying or working. The four cells are tutorial, how-to, reference and explanation, each serving one reader need. Redrawn; the layout is not the original site's diagram. View full size ▸

1. What happened

Procida published early versions of these ideas while at Divio between 2014 and 2021, later judged that several aspects of them were wrong, then took the work independent and kept refining it on its own site[1]Procida, D. Diátaxis. The two-axis derivation and the notes on the Divio years and 2021 checked against the primary site. Available at diataxis.fr. The home page, the foundations page and the colophon of the primary site were checked. The names and etymology of the four types match word for word. Attribution note: an early version was published during the author's time at Divio (2014–2021), and Procida later acknowledged that he had misjudged parts of it. “2021” refers to a Software Sustainability Institute fellowship, not the year of first publication. The breadth of adoption is the site's own account and has not been verified by a third party..

The derivation is not an arbitrary taxonomy. Reader situations divide along two axes, practice against cognition, knowing-how against knowing-that, and studying against working. Two by two yields four types, each serving one need with its own writing criteria.

A tutorial is guided practice while learning. A how-to is the steps to an outcome while working. Reference is looking information up while working. Explanation is seeking understanding while learning.

The failure mode of mixing them is one everybody has seen: a "tutorial" that opens by teaching operations, turns into a parameter table in the middle, and closes with design philosophy, so every kind of reader has to skim.

Attribution where due: The framework has no single year of origin. Early versions were published during the author's time at Divio, and 2021 refers to a fellowship, so it should not be cited as proposed in 2021. The breadth of adoption, given as hundreds of documentation projects, is the site's own account and has not been independently verified; keep that qualification when citing[1]Procida, D. Diátaxis. The two-axis derivation and the notes on the Divio years and 2021 checked against the primary site. Available at diataxis.fr. The home page, the foundations page and the colophon of the primary site were checked. The names and etymology of the four types match word for word. Attribution note: an early version was published during the author's time at Divio (2014–2021), and Procida later acknowledged that he had misjudged parts of it. “2021” refers to a Software Sustainability Institute fellowship, not the year of first publication. The breadth of adoption is the site's own account and has not been verified by a third party..

2. Why this matters to you

To decide whether a document should be split, ask which quadrant the reader is in right now, not which topic the content belongs to.

In this site's framing of knowledge system design, this is also one of three questions that routinely get answered together when they should not be: where things go, which is organisation; how you find them again, which is navigation; and what type to write, which is this framework. The three are orthogonal and answering them jointly makes each one worse.

Carrying this into personal notes is our practice, not a rule of the framework. We keep the operating manual and the conceptual explanation we write for ourselves in two files, because they update on different rhythms and fail in different ways. The framework itself asks that one passage not serve two needs at once; it does not prescribe separate files[1]Procida, D. Diátaxis. The two-axis derivation and the notes on the Divio years and 2021 checked against the primary site. Available at diataxis.fr. The home page, the foundations page and the colophon of the primary site were checked. The names and etymology of the four types match word for word. Attribution note: an early version was published during the author's time at Divio (2014–2021), and Procida later acknowledged that he had misjudged parts of it. “2021” refers to a Software Sustainability Institute fellowship, not the year of first publication. The breadth of adoption is the site's own account and has not been verified by a third party..

Verification layer · Members
The guided layer of this node is open to all readers.
Verification details and failure boundaries are for members.
Subscribe yearly ▸Read the member edition ▸

Lab cases Written only where there is evidence

No field record for this node yet.

References

How to read the source notes “Checked against the primary site” means the claim was compared with the project's own website. Definitions as of 2026-09-20.

  1. [1] Procida, D. Diátaxis. https://diataxis.fr/ The two-axis derivation and the notes on the Divio years and 2021 checked against the primary site. An early version was published during the author's time at Divio, 2014–2021. ↩

↳ Is a citation wrong?

Tell the editor privately: a correction, a counter-example or where it applies

An editor reviews submissions once a week. Once a note is handled, its summary and response are listed on the discussion and response record; nothing is published before then. No sign-up is needed, and the nickname may be left blank.

What are you submitting?
Set a public name to be credited by name ▸
Submit anonymously, without signing in

Signing in lets you follow the status on your page. What you have written is kept.

You are signed in: this note is linked to your account, visible only to you and the editor, so you can follow its status on your page. The text is never published. Full privacy policy ▸

Submit anonymously instead, not linked to your account ▸

No email is collected. Your original text and nickname are read only by the editor and are never published; the discussion and response record carries only a summary the editor writes. The human check is provided by Cloudflare Turnstile. To limit abuse, the system keeps a hash of your IP address, not the address itself. Your original text is stored with our cloud provider and can be deleted on request. Full privacy policy ▸

Response record ▸