nandi/ori · SKILL.md

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