forked from bots-garden/ori
name: diataxis-doc
description: Document a project using the Diátaxis methodology (https://diataxis.fr). Organises documentation into four distinct quadrants — Tutorials (learning), How-to guides (solving a task), Reference (looking information up), Explanation (understanding) — along the two axes action/cognition and acquisition/application. Use when creating or restructuring a project's documentation in a rigorous, readable, user-needs-driven way.
Diátaxis Documentation Skill
Description
Guides the creation and restructuring of a project's documentation according to the
Diátaxis methodology (Daniele Procida — https://diataxis.fr). Diátaxis is not a rigid
template: it is a compass that guarantees every documentation page serves exactly one
clearly identified user need, and that all four fundamental needs are covered.
The strength of the method: it solves the three problems of any documentation —
content (what to write), style (how to write it) and architecture
(how to organise it) — by reducing them to two simple questions.
When to Use
- When a project has no documentation, or a "catch-all" documentation
- When existing docs mix tutorials, recipes, reference and explanation in the same pages
- When users "can't find" the information despite voluminous docs
- When you want maintainable documentation that grows in small increments
- After adding a feature, to document it in the right place without reorganising everything
Core Principle: the two axes
The whole method rests on two orthogonal axes. They do not merely cover the territory of
documentation — they define it. This is why there are necessarily four quadrants,
neither three nor five.
ACTION (practical know-how)
▲
│
TUTORIALS │ HOW-TO GUIDES
(learning by doing) │ (achieving a goal)
│
ACQUISITION ────────────────────┼──────────────────── APPLICATION
(studying a skill) │ (applying a skill)
│
EXPLANATION │ REFERENCE
(understanding, thinking) │ (looking information up)
│
▼
COGNITION (theoretical knowledge)
| Quadrant | Action/cognition axis | Acquisition/application axis | The user's question |
|---|---|---|---|
| Tutorial | Action | Acquisition | "Teach me to get started" |
| How-to guide | Action | Application | "How do I do X?" |
| Reference | Cognition | Application | "What are the exact details of X?" |
| Explanation | Cognition | Acquisition | "Can you explain why / the context?" |
The four quadrants in detail
1. TUTORIALS — learning-oriented
A tutorial is a guided lesson, an experience under a teacher's direction. Its goal is NOT
to accomplish a real task, but to make the beginner acquire a skill. The teacher is
responsible for the student's success.
Writing rules (mandatory):
- ✅ Announce the destination up front ("by the end, you will have built…"), not what will be "learned"
- ✅ Produce a visible result at every step, however small
- ✅ Guarantee perfect reliability: every command must work for everyone, every time
- ✅ Show the actual expected output ("you should see: …")
- ✅ Use "we" ("we will now…") and the direct imperative ("Type this")
- ✅ Flag common mistakes at the point where they can occur
- ❌ Minimise explanation to the extreme — a tutorial is NOT the place for explanation. Link to it instead.
- ❌ No alternatives, no options, no digressions — a single path to success
- ❌ Do not explain the "why" in detail (it breaks the learning flow)
2. HOW-TO GUIDES — task-oriented
A how-to guide is a recipe for reaching a specific goal. It addresses an already
competent user who knows what they want to do. "How do I deploy?", "How do I enable
caching?".
⚠️ Key distinction from a tutorial: "Someone who expects a recipe and receives a cooking
lesson will be disappointed and annoyed." Tutorial = lesson; guide = recipe.
Writing rules:
- ✅ Title = the task, stated clearly: "How to {do X}"
- ✅ Start from a real problem, not from a feature of the tool
- ✅ Contain only the steps needed for the task
- ✅ Stay adaptable to the real world ("if you use Y, do this instead") — a guide covers variants
- ✅ Assume the user already knows what they want to accomplish
- ❌ Do not teach the basic concepts (that is the tutorial's job)
- ❌ Do not drown the recipe in explanation (link to the explanation)
3. REFERENCE — information-oriented
Reference is a neutral, exhaustive technical description of the machinery: the commands,
options, parameters, structures. It is a map of the territory, austere and reliable, that
you consult (you do not read it end to end).
Writing rules:
- ✅ Describe, do nothing else: no instruction, no explanation, no opinion
- ✅ Accuracy and completeness: every parameter, default value, type, error
- ✅ Standard, predictable structure: the same format for every entry (tables, lists)
- ✅ Mirror the product's structure: the reference's organisation reflects that of the code
- ✅ Include usage examples, without drifting into explanation
- ❌ Do not teach, do not tell the "why" — link to tutorials and explanations
Mental model: a nutrition label. Factual, standardised, rigorous, with no recipe and no
marketing pitch.
4. EXPLANATION — understanding-oriented
Explanation steps back. It answers "Can you tell me about…?". It connects concepts, gives
context, history, design decisions, rejected alternatives. It is the documentation you read
"in the bath", away from active work.
Writing rules:
- ✅ Make connections between topics, take a wider view
- ✅ Give the context: history, decisions, constraints, rejected alternatives
- ✅ Discuss the why, the trade-offs, the possibilities
- ✅ Allow opinion and acknowledge multiple points of view
- ✅ Stay bounded to one topic, so it does not absorb content that belongs elsewhere
- ❌ Do not give step-by-step instructions (that is the guides'/tutorials' job)
- ❌ Do not become a reference (no exhaustive parameter lists)
The Compass — choosing the right quadrant
When you do not know where a piece of content belongs (or when the writing "gets stuck"),
answer two questions:
1. Does the content inform ACTION or COGNITION?
(practical steps ──vs── theoretical knowledge)
2. Does it serve the ACQUISITION or the APPLICATION of a skill?
(the user is learning ──vs── the user is doing)
| If the content says… | …informs | …and serves | → then it is a |
|---|---|---|---|
| "teach me by doing" | action | acquisition | Tutorial |
| "help me do this" | action | application | How-to guide |
| "give me the exact information" | cognition | application | Reference |
| "help me understand" | cognition | acquisition | Explanation |
Symptom of a misfiling: if a page forces you to mix two styles (e.g. explaining the why
in the middle of a recipe), it contains two distinct pieces of content → split it and link
the parts to each other.
The compass applies at every scale: a whole document, a section, or even a single sentence.
Recommended folder architecture
Four folders, one per quadrant, plus an index:
docs/ (or ./new.docs, ./documentation, etc.)
├── README.md ← index: explains the structure and orients the reader
├── tutorials/ ← guided learning
│ └── getting-started.md
├── how-to/ ← task-oriented recipes
│ ├── do-x.md
│ └── do-y.md
├── reference/ ← exhaustive technical description
│ ├── cli.md
│ └── configuration.md
└── explanation/ ← understanding, context, decisions
├── architecture.md
└── design-choices.md
Architecture rules:
- ✅ Folder names make the quadrant obvious (tutorials / how-to / reference / explanation)
- ✅ The index (
README.md) briefly explains the four types and links to each - ✅ Documents link to each other: a tutorial links to the reference and the explanation rather than including them
- ✅ Folders may be named in the documentation's own language (
tutoriels/,guides-pratiques/, …) — stay consistent
Bilingual architecture (the "Both" option)
When the user wants both languages, use one subfolder per language, each containing its own
complete four-quadrant structure. A root index acts as the language selector:
docs/
├── README.md ← language selector (links to fr/ and en/)
├── fr/
│ ├── README.md ← French index
│ ├── tutorials/
│ ├── how-to/
│ ├── reference/
│ └── explanation/
└── en/
├── README.md ← English index
├── tutorials/
├── how-to/
├── reference/
└── explanation/
Bilingual rules:
- ✅ Cross-links stay inside a single language (a FR doc never links to an EN doc, and vice versa)
- ✅ Quadrant folder names are identical in both languages (
tutorials/,how-to/…) to keep a 1-to-1 symmetry - ✅ File names may be translated (
premiers-pas.md↔getting-started.md) or kept identical — stay consistent - ✅ The content is translated, not merely copied: adapt the examples where necessary
- ❌ Do not mix two languages in the same file
- ❌ Do not duplicate only one of the two indexes — each language has its own
Acceptable alternative for small projects: a per-file language suffix
(getting-started-en.md/premiers-pas-fr.md) in a flat structure. Reserve this for cases
where creating subfolders would be disproportionate.
Iterative workflow (the heart of the method)
Diátaxis is not a grand plan to be executed in one go. It is an organic process: the
structure emerges from within, "one cell at a time". The documentation must always be
"complete, not finished" — useful and well-formed at every stage, while remaining open.
The loop, to be repeated indefinitely:
1. CHOOSE — take a small piece (a paragraph, a page)
2. ASSESS — does it serve one clear need? Is it in the right quadrant?
3. DECIDE — identify ONE concrete improvement
4. ACT — apply it and publish immediately
Workflow rules:
- ✅ Work small: one improvement at a time, published right away
- ✅ "Every step in the right direction deserves to be published immediately"
- ❌ Do NOT create large empty sections "to be filled in later"
- ❌ Do NOT tear everything down to rebuild it all at once
Skill application phases
Phase 1 — Gathering information
First question, MANDATORY — the language of the documentation.
Before anything else, ask the user which language(s) the documentation should be produced in,
via AskUserQuestion, with exactly these three options:
| Option | Effect on the output |
|---|---|
| French | All documentation in French, at the root of the chosen location. |
| English | All documentation in English, at the root of the chosen location. |
| Both | Bilingual documentation: one subfolder per language (see "Bilingual architecture"). |
This choice determines the folder architecture (mono- or bilingual) and the language of
every document, title and link. Never infer it from the language the user is writing to
you in, or from the language of the existing code and comments: ask. If documentation already
exists in one language and the user wants "both", add the missing language without rewriting
what is already there.
Exception — invoked by another skill. When this skill is invoked from another skill that
has already fixed the language, do not ask: use the language it specifies and go straight to
Phase 2. Themethodical-devskill always specifies Both (English + French), because it
requires bilingual documentation for every change. Asking again in that case is a redundant
prompt for a question that is already settled.
Then ask (via AskUserQuestion where relevant):
- Documentation target: which project / which scope should be documented?
- Audience: beginners discovering the tool? advanced users? contributors?
- Location: where should the docs be written? (
docs/,./new.docs, etc.) Must existing content be preserved? - Existing material: is there already documentation to reuse / reorganise?
Phase 2 — Mapping the subject matter
Before writing, understand factually what is being documented:
- Explore the code (entry point, commands, configuration, features)
- List the user-facing features and the machinery (CLI, config, API…)
- Spot the existing documentation so as not to reinvent it
- Produce a list of topics to be filed into the four quadrants
Phase 3 — Filing with the Compass
For each identified topic, apply the compass and file it into a quadrant. Build a plan as a
table:
| Topic | Quadrant | File |
|-----------------------------|---------------|----------------------------------|
| First steps | Tutorial | tutorials/getting-started.md |
| Enabling feature X | How-to | how-to/enable-x.md |
| Configuration options | Reference | reference/configuration.md |
| Why this architecture | Explanation | explanation/architecture.md |
Present this plan to the user and have it approved before writing.
Phase 4 — Writing quadrant by quadrant
Write the documents while strictly respecting the writing rules of the corresponding
quadrant (see the templates below). At the end of each document, apply the quadrant's checklist.
Phase 5 — Index and cross-links
- Create / update
README.md(the index) explaining the Diátaxis structure and orienting the reader - Check that documents link to each other in the right direction (tutorial → reference/explanation, etc.)
Phase 6 — Final validation
Apply the global checklist (see below) and present the result.
Templates
Template — Tutorial
# Tutorial: {what the reader will have accomplished}
By the end of this tutorial, you will have {concrete, visible result}.
No prior knowledge of {X} is required.
## Prerequisites
- {strictly what is required for EVERY step to work}
## Step 1 — {first concrete action}
Type:
\`\`\`bash
{exact command}
\`\`\`
You should see:
\`\`\`
{actual expected output}
\`\`\`
We have just {result of the step, in one sentence}.
## Step 2 — {next action}
...
## What now?
You have built {recap}. To go further:
- To accomplish specific tasks → see the [how-to guides](../how-to/)
- To understand how it works → see the [explanation](../explanation/)
Template — How-to guide
# How to {accomplish the task}
This guide shows how to {task}. It assumes you {skill prerequisite}.
## Steps
1. {step}
2. {step}
## Variants
- If you use {case A}, do {…} instead
- For {case B}, add {…}
## See also
- Options reference: [reference](../reference/…)
- Why it works this way: [explanation](../explanation/…)
Template — Reference
# Reference: {component}
> Neutral, exhaustive description of {component}.
## {Sub-component / command / section}
| Field / Option | Type | Default | Description |
|----------------|------|---------|-------------|
| {name} | {type} | {default} | {factual description} |
### Example
\`\`\`{lang}
{minimal usage example}
\`\`\`
### Errors
| Error | Cause |
|-------|-------|
| {message} | {factual cause} |
Template — Explanation
# {Topic} — explanation
## What is this about?
{framing of the topic, overview}
## Why it is designed this way
{context, constraints, decisions}
## Rejected alternatives
{what was considered and why it was rejected}
## How it relates to the rest
{connections with the other parts of the system}
Checklists
Per-quadrant checklist
Tutorial:
□ Is the destination announced up front?
□ Does every step produce a visible result?
□ Do all commands work without fail (perfect reliability)?
□ Is the actual expected output shown?
□ No alternatives / options / digressions?
□ Is explanation kept minimal (linked, not included)?
How-to guide:
□ Does the title state a concrete task ("How to…")?
□ Does it start from a real problem, not a feature?
□ Does it contain only the necessary steps?
□ Does it cover real-world variants?
□ Does it avoid teaching the basics (assumes competence)?
Reference:
□ Purely descriptive (no instruction, no explanation, no opinion)?
□ Exhaustive (every parameter, default, type, error)?
□ Standard, predictable format (same structure throughout)?
□ Mirrors the product's structure?
□ Contains examples without drifting into explanation?
Explanation:
□ Does it step back and make connections?
□ Does it give the context (history, decisions, constraints)?
□ Does it discuss the why and the rejected alternatives?
□ Does it stay bounded (not absorbing reference/guide material)?
□ Is it free of step-by-step instructions?
Global checklist (Phase 6)
□ Was the language (FR / EN / both) asked for — or taken from the invoking skill — and respected?
□ If bilingual: one subfolder per language, cross-links internal to each language?
□ Do all four quadrants exist (at least one document each)?
□ Does every document serve exactly ONE clearly identified need?
□ Do the folder names make the quadrant obvious?
□ Does the index (README) explain the structure and orient the reader?
□ Do documents link to each other (no duplication)?
□ Are there no empty "to be filled in later" sections?
□ Is every document "complete, not finished" (useful right now)?
Markdown formatting
Write Markdown for readers who soft-wrap in their editor, not for a fixed column
width. Do not hard-wrap prose: never insert a line break in the middle of a
sentence or paragraph.
- One logical line per block. A paragraph is a single line. A list item is a
single line (its continuation text stays on the same line, not wrapped under
the bullet). A blockquote paragraph is a single>line. - Blank lines separate blocks — keep exactly one blank line between
paragraphs, list items groups, headings, and code fences. - Leave code, tables, and headings alone. Fenced code blocks keep their
internal newlines verbatim; table rows stay one row per line; a heading is its
own line.
This keeps diffs meaningful (a reworded sentence changes one line, not a whole
reflowed block) and matches how the rendered output looks anyway. If you are
editing a file that was previously hard-wrapped, unwrap the blocks you touch.
Strict Rules
You must NEVER:
- ❌ Mix two quadrants in the same document (recipe + explanation, reference + tutorial…)
- ❌ Put detailed explanation into a tutorial or a how-to guide
- ❌ Put step-by-step instructions into a reference or an explanation
- ❌ Create empty folders / sections in anticipation
- ❌ Brutally reorganise all the existing documentation at once (work in increments)
- ❌ Duplicate content across quadrants instead of linking
- ❌ Hard-wrap prose — no line break in the middle of a sentence or paragraph (see "Markdown formatting")
You must ALWAYS:
- ✅ File every piece of content with the compass (action/cognition × acquisition/application)
- ✅ Respect the writing rules specific to the quadrant
- ✅ Guarantee absolute reliability in tutorials (every command mentally tested)
- ✅ Keep the reference neutral, exhaustive and structured
- ✅ Link documents to each other rather than merging them
- ✅ Work in small publishable increments ("complete, not finished")
- ✅ Write each paragraph, list item, and blockquote as a single unwrapped line
Notes
Diátaxis imposes no technology (Markdown, Sphinx, MkDocs, Docusaurus… it does not matter). What
counts is the clean separation of the four needs. Documentation that respects this
separation is easier to write, to maintain and — above all — to use: every reader immediately
knows where to go depending on whether they want to learn, do, look up or
understand.
Canonical reference: https://diataxis.fr
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 |
|