--- 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. The `methodical-dev` skill 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): 1. **Documentation target**: which project / which scope should be documented? 2. **Audience**: beginners discovering the tool? advanced users? contributors? 3. **Location**: where should the docs be written? (`docs/`, `./new.docs`, etc.) Must existing content be preserved? 4. **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 ```markdown # 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 ```markdown # 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 ```markdown # 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 ```markdown # {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