Diátaxis

Diátaxis is a systematic approach to technical documentation, formalised by Daniele Procida (Canonical) around 2017 and now used by Django, Cloudflare, GitLab, NumPy, Gatsby, and dozens of other major OSS projects.

The name comes from Greek diá (“across”) + táxis (“arrangement”) — a deliberate ordering across four axes.

Authoritative source	https://diataxis.fr
Author	Daniele Procida
Local home in the kit	`template/docs/user-manual/`
Slot in pentaglyph	#4 of 5 — the user-facing docs layer

What problem does Diátaxis solve?

Most technical docs collapse into one of two failure modes:

A single “docs” pile where tutorials, references, explanations, and how-tos are interleaved. The reader cannot find anything.
A two-bucket split (e.g. “Getting Started” + “API Reference”) that fails to distinguish learning-by-doing (tutorial) from solving-a-known-problem (how-to), or understanding (explanation) from looking-up (reference).

Diátaxis observes that there are exactly four distinct kinds of reader need — and that mixing two in one doc serves neither.

The four quadrants

	Practical steps	Theoretical knowledge
Learning-oriented	Tutorials	Explanation
Work-oriented	How-to guides	Reference

Tutorials — learning by doing

The reader is a first-time learner. The author leads them by the hand through a guaranteed success. Hide trade-offs. Hide alternatives. The goal is first successful run, not understanding.

Example: Getting started with pentaglyph.

How-to guides — solving a problem

The reader already knows what they want to do and needs the recipe. Concrete steps to a known goal. Trade-offs may appear if they’re decision-relevant.

Example: How to write an ADR.

Reference — looking something up

The reader needs precise facts. Dry, complete, machine-like. No narrative, no hand-holding. Often the longest and least-read content, but indispensable when needed.

Example: Template inventory.

Explanation — understanding why

The reader already uses the system and wants to understand why it’s shaped this way. Discursive, opinionated, theoretical. The “essay” quadrant.

Example: Why pentaglyph.

The discipline

If a doc straddles two quadrants, split it.

A tutorial that tries to also be reference becomes a wall of caveats nobody reads. A how-to that tries to explain becomes a digression nobody finishes. The four-quadrant separation is the entire value proposition — softening it defeats the framework.

How pentaglyph uses Diátaxis

template/docs/user-manual/
├── tutorials/         ← first-time success walkthroughs
├── how-to/            ← recipes for known problems
├── reference/         ← precise facts, dry
└── explanation/       ← discursive "why" content

Two different docs/ in this repo. docs/ (the user manual for pentaglyph itself) and template/docs/user-manual/ (what gets copied into your project by pentaglyph init). Don’t confuse them.

This site you’re reading is a Diátaxis-organised manual for pentaglyph. The sidebar maps directly to the four quadrants (plus “Start” for first-time orientation and “Standards” for this reference page).

When to use Diátaxis

Any project shipping user-facing docs (developer tools, libraries, SaaS products).
Especially valuable when multiple authors contribute — the quadrants prevent ad-hoc structure drift.

When NOT to use Diátaxis

Pure internal architecture docs (use arc42 instead).
Single-page READMEs — overhead exceeds value.

Authoritative references

Official site: https://diataxis.fr (read this first; it’s short)
Author’s home page: https://evildmp.org (Daniele Procida)
Talk: What nobody tells you about documentation — Daniele Procida at PyCon US
Adoption examples: Django docs, Cloudflare Workers docs, GitLab handbook, NumPy