Diataxis

Diátaxis

A runbook for producing and fixing technical documentation with the Diátaxis framework. Diátaxis splits documentation into four modes — tutorials, how-to guides, reference, explanation — because they answer four different user needs that pull in opposite directions. The single idea that makes it work:

Most documentation problems are a single thing: content that tries to serve more than one need at once. Separate the four modes and most confusion dissolves.

Diátaxis is descriptive, not prescriptive — a way to understand documentation, not a template to fill in. Don't wait to understand the whole framework before applying it: pick one small thing, classify it, improve it, publish, repeat.

When to Apply

Use this skill when:

• Writing or generating new documentation of any kind (README, API docs, guide, onboarding, developer docs) — decide which mode(s) the content needs before writing it.
• A page is confusing, bloated, or "tries to do everything" — diagnose the type-mixing and split it.
• *Users can't get started, can't complete a task, can't find a fact, or don't understand why*** — locate the missing or weak mode.
• Restructuring or auditing an existing doc set — apply the small-step workflow instead of a big rewrite.
• You're unsure whether something is a tutorial, how-to, reference, or explanation — run the compass.

Do not reach for this skill for pure prose/copy-editing within an already-correct mode (use a copywriting skill), or for design/spec/proposal documents — those are mostly explanation and are better served by dev-rfc or feature-spec.

The four modes

Each mode serves a different user, in a different situation, with a different content style. The quickest way to keep them straight:

Two of them serve practical steps (tutorial, how-to); two serve theoretical knowledge (reference, explanation). Two serve someone acquiring skill / studying (tutorial, explanation); two serve someone applying skill / working (how-to, reference).

The compass — decide what you are writing

When you are unsure which mode a piece of content belongs to, answer two questions. This is the master decision tool; the full tree is in compass-tree.md.

1. Does it inform _action_ or _cognition_? — practical steps (doing) vs theoretical knowledge (thinking). 2. Does it serve _acquisition_ or _application_? — study (learning) vs work (applying what you know).

Read as a decision: informs action + serves acquisition → tutorial; informs action + serves application → how-to guide; informs cognition + serves application → reference; informs cognition + serves acquisition → explanation. Apply the compass at any scale — a whole document, a section, or a single sentence that has drifted into the wrong mode.

Common Symptoms

Start here. Match the situation, open its tree. Severity reflects how badly the reader is failed right now (see symptoms.md).

How to use

1. Match the symptom in the table above and open its tree in references/. For a large existing corpus, run bash references/queries/scan-docs.sh <docs_root> first — it triages which pages show signals of more than one mode, so you know where to point the compass. 2. Classify with the compass — decide which of the four modes the content serves. When in doubt, open compass-tree.md. 3. Read the matching type guide — tutorials, how-to-guides, reference, or explanation — for how to write that mode well, and what to keep out of it. 4. Work in small steps. Follow workflow.md: choose something small → assess it → decide one next action → do it and publish. Never tear everything down to restructure top-down. 5. Assess against quality. Use quality.md to judge functional quality (accuracy, completeness, consistency) and deep quality (does it feel good to use, anticipate the user's needs). 6. Record an audit with assets/templates/report.md when reviewing an existing doc set, so the same gaps don't get re-litigated each time.

Setup

This skill uses an optional config.json to know where your docs live and where to log audits. On first use, if docs_root is empty and you are auditing an existing doc set, ask the user (via AskUserQuestion) for the documentation directory, then save it. The skill works without config — fall back to asking inline. Never block on missing config.

Gotchas

The recurring traps of applying Diátaxis — empty structure-first scaffolding, "balancing" the four types instead of separating them, explaining inside a tutorial — are in gotchas.md. Read it before your first restructure.

Related skills

• skill-authoring — authoring Agent Skills; their SKILL.md is itself a Diátaxis problem (navigation + reference, not a tutorial).
• human-copywrite / humanize — once a doc is in the right mode, these tighten the prose so it reads naturally.
• dev-rfc / feature-spec — design and spec documents are mostly explanation; reach for those when the artifact is a proposal, not user documentation.

Documentation Audit Report: {doc set / page}

Date: {YYYY-MM-DD} Reviewer: {agent or user} Scope: {what was reviewed — a single page, a section, or the whole corpus} Docs root: {path or URL}

Summary

{1–2 sentences: the dominant problem and the single highest-value next action.}

Coverage map (the four modes)

Which user needs are served, and how well. A blank "Exists?" cell is a gap (see gaps-tree).

Per-page findings

Timeline

Root Cause

{The dominant pattern. Almost always one of two: type-mixing (one page serving more than one user need at once) or a missing quadrant (a user need with no content at all). State which, with the evidence from the findings above.}

Resolution

{What to do — the splits to make, the modes to create, the passages to move. Reference the trees/guides used: compass-tree, wrong-type-tree, gaps-tree, and the four type guides.}

Action Items

Smallest-useful-first; each item independently shippable (workflow: choose → assess → decide → do → publish). Do not bundle these into a single big-bang restructure.

• [ ] {one small, published improvement}
• [ ] {next small improvement}
• [ ] {the next worst gap to create, by failing user need}
• [ ] Append a one-line entry to the audit log (config.json → audit_log)

Gotchas

The recurring traps of applying Diátaxis. The first ones are the classic mistakes the framework exists to prevent. Append new ones (with dates) as real use surfaces them.

Building empty structure first

The most common failure: creating the four containers (tutorials/, how-to/, reference/, explanation/) with a skeleton of headings and no content, then trying to file everything in. Empty structure advertises content that isn't there and the migration stalls half-built — "it's horrible." Let structure emerge from improving real content instead. See restructure-tree.md. Added: 2026-05-22

"Balancing" the four modes inside one page

Diátaxis is about separation, not balance. Trying to give every page a little tutorial, a little how-to, a little reference, and a little explanation reproduces exactly the type-mixing it's meant to cure. One page → one user need. When a page wants to do two things, split it (wrong-type-tree.md), don't balance it. Added: 2026-05-22

Explaining inside a tutorial (the #1 drift)

The strongest pull in all of documentation is to stop and explain why mid-tutorial. It overwhelms the beginner and breaks the rhythm of doing. A tutorial is not the place for explanation — link out to an explanation page and keep the learner moving. (The mirror traps: how-to guides that lecture, reference that editorialises.) See tutorials.md. Added: 2026-05-22

Writing how-to guides about the tool, not the goal

"To shut off the water, turn the tap clockwise" describes operating machinery — it isn't a how-to guide, because it doesn't help with what the user is trying to do. Name the real-world goal ("how to stop a leak") and title it so a searching user recognises it instantly. Tool-described steps belong in reference. See how-to-guides.md. Added: 2026-05-22

Confusing the two same-axis pairs

The hard classifications are the within-axis ones. Tutorial vs how-to (both inform action): is the reader a beginner you're teaching, or a competent user pursuing their own goal? Reference vs explanation (both inform cognition): is it a neutral fact to look up, or discussion to build understanding? Decide by the reader's situation, not the topic. See compass-tree.md. Added: 2026-05-22

Treating Diátaxis as a rigid plan or a big migration

Diátaxis is a guide, not a project plan. Top-down "let's reorganise all the docs" projects stall and ship nothing for months. Work one small thing at a time and publish each change — structure emerges organically. See workflow.md. Added: 2026-05-22

Refusing to ship until it's "finished"

Documentation is never finished — but it should always be complete (every part useful at its current stage). Withholding improvements until the whole set is perfect is how the empty-scaffold trap and the big-migration trap both start. Publish the small improvement now. See workflow.md. Added: 2026-05-22

Misreading the compass because the reader wasn't named

The same sentence can be tutorial, how-to, reference, or explanation depending on who reads it and why. Running the compass on content without first fixing the unit and the reader's situation produces a confident wrong answer. Name the reader and their situation first. See compass-tree.md. Added: 2026-05-22

Decision Tree: The Compass (master)

Symptom: "Write docs for X" / "document this", or simple uncertainty about which mode a piece of content belongs to. Start here whenever the mode is unknown — every other tree assumes you already know which of the four modes you're in.

Precondition — name the unit and the reader. The compass works at any scale: a whole document, a section, or a single sentence that has drifted. Before classifying, fix (a) the unit of content you're judging and (b) who reads it and what situation they are in. The same fact can belong to different modes depending on the reader's need, so the reader is part of the question.

Pick the unit of content + the reader's situation
│
├── Q1. Does this content inform ACTION (practical steps — doing)
│        or COGNITION (theoretical knowledge — thinking)?
│
├── ACTION ─► Q2. Acquisition or application?
│   │         (Is the reader STUDYING/learning, or WORKING with a known goal?)
│   │
│   ├── ACQUISITION (study) → TUTORIAL
│   │   Action: write it as a guided lesson — open tutorials.md. Take responsibility for
│   │   the beginner, make it work every time, and keep explanation out.
│   │
│   └── APPLICATION (work) → HOW-TO GUIDE
│       Action: write it as goal-oriented directions — open how-to-guides.md. Name the real
│       problem, sequence the steps, link out for concepts and full specs.
│
└── COGNITION ─► Q2. Acquisition or application?
    │
    ├── APPLICATION (work) → REFERENCE
    │   Action: write it as neutral description led by the product's structure — open
    │   reference.md. Describe and only describe, be consistent, link out for how-to and why.
    │
    └── ACQUISITION (study) → EXPLANATION
        Action: write it as a discursive piece *about* the topic — open explanation.md.
        Make connections, give context and the "why", and bound the scope.

If you're stuck on the two questions

Phrase them whichever way unsticks you — they're the same axes:

• "Am I writing for study or for work?" (acquisition vs application)
• "Is this content engaged in doing or in thinking?" (action vs cognition)
• "Does the user need practical steps or knowledge right now?"

Decision criteria

Terminal actions

• One clear mode → open that mode's guide and write/route the content there.
• The unit answers "both" (it serves two needs at once) → it is really two pieces of content. Go to wrong-type-tree.md and split it.
• The unit doesn't exist yet and you're deciding what to create for a failing user need → go to gaps-tree.md.

Record any classification or split in ../assets/templates/report.md.

Explanation — understanding-oriented

Explanation is a discursive treatment of a subject that permits reflection. It is understanding-oriented. Unlike the other three modes, explanation is read away from the product, at leisure — it deepens and broadens the reader's understanding. It is documentation about a topic: the article about cooking, not the recipe.

Explanation depends on, and illuminates, prior experience. It is reflection, and reflection happens after engagement — which is why explanation is the mode most easily skipped, and most easily bloated.

What makes explanation different

• Not tied to action (unlike tutorials and how-to guides) and not tied to the machinery (unlike reference). It takes a higher, wider view, treating the topic as a bounded area of knowledge.
• It's "about" the subject. The natural title is "About X" — about authentication, about the data model — which is a good test of whether you're really writing explanation.
• It's the least bounded mode, so it's the hardest to write well and the easiest to let absorb material that belongs in the other three.

Principles

• Make connections. Relate the topic to other things — even things outside the immediate subject, if it helps the reader build a mental model. Connections are what turn facts into understanding.
• Provide context and background. Explain why things are the way they are: design decisions, historical reasons, technical constraints, alternatives that were rejected. This is the home for every "why" you kept out of the other modes.
• Talk about the subject — frame around the topic, not the task. Discuss; don't instruct. "About user authentication", not "How to authenticate a user".
• Admit opinion and perspective. Explanation can and must weigh alternatives, counter-examples, and different approaches to the same question. A considered point of view is appropriate here (and nowhere else).
• Keep it bounded. Deliberately fence the scope of an explanation, or it will sprawl and start swallowing instruction and description that belong elsewhere. Decide what the piece is about — and what it is not about.

Keep out of explanation

Language patterns

• Historical/causal: "The reason for x is that, historically, y…"
• Comparative judgement: "w is better than z, because…"
• Analogy: "An x in system y is analogous to a w in system z…"
• Weighing alternatives: "Some users prefer w. This can be a good approach, but…"

Smell test

If it reads like a lecture you'd give to help someone understand the topic — connecting, contextualising, weighing options — it's explanation. If it has started telling the reader to do something or listing exact specs, those parts belong in another mode.

Reference: https://diataxis.fr/explanation/

Decision Tree: Gaps / Missing Quadrant

Symptom: users can't get started, can't accomplish a task, can't find a fact, or don't understand why. Each failing need points to a specific missing or weak mode. Diagnose by the user need that is failing, not by the topic.

Which user need is failing?
│
├── "I can't get started / I don't know where to begin" — a NEWCOMER, learning
│   └── Missing or weak TUTORIAL. The acquisition path is closed.
│       Action: create a learning-oriented tutorial that takes a beginner to a first,
│       guaranteed success → tutorials.md.  Severity P1.
│
├── "How do I accomplish <specific goal>?" goes unanswered — a COMPETENT user, working
│   └── Missing HOW-TO GUIDE for a real task.
│       Action: write goal-oriented directions named after the real problem →
│       how-to-guides.md.  Severity P1.
│
├── "What exactly is X? what options/params exist?" — facts missing, scattered,
│   inconsistent, or not trusted
│   └── Missing or weak REFERENCE.
│       Action: create reference led by the product's structure — describe and only
│       describe, make it consistent → reference.md.  Severity P2.
│
├── "Why is it like this? I have no mental model; I keep misusing it"
│   └── Missing EXPLANATION.
│       Action: write an "About X" piece — context, the why, connections, trade-offs →
│       explanation.md.  Severity P2.
│
└── Several / all of the above are failing
    └── The corpus is thin across modes. DON'T build all four at once.
        Terminal: go to restructure-tree.md and grow them one small step at a time,
        worst-failing need first.

Confirm it's a real gap, not findability

A "missing" mode is sometimes content that exists but can't be found or trusted. Check before writing:

Terminal actions

• Each leaf → create the missing mode by opening its type guide and writing it.
• Breadth problem (several gaps) → restructure-tree.md, worst-failing need first.
• Content exists but is mislocated/misnamed → wrong-type-tree.md (extract/split) or fix navigation — don't write a duplicate.

Record the gap and the mode created in ../assets/templates/report.md.

How-to guides — goal-oriented

A how-to guide is a set of directions that guide the reader through a problem or towards a result. It is goal-oriented. It serves the work of an already-competent user who knows what they want to achieve and needs to get it done correctly. A how-to guide is like a recipe in a cookbook: a sequence of steps to a specific end.

A how-to guide answers: "How do I achieve this specific goal?" It assumes competence — the reader is in charge and knows roughly what they're doing. That is exactly what separates it from a tutorial, where you take charge of a beginner.

What makes a how-to guide different

• vs [tutorial](tutorials.md): a tutorial is a lesson for a beginner you take responsibility for; a how-to guide assists a competent user pursuing their own goal. Same steps, opposite user.
• vs [reference](reference.md): a how-to guide is a sequence of actions; reference is description. Link to reference for the details — don't inline them.
• vs [explanation](explanation.md): a how-to guide addresses a real-world problem, not concepts. Keep the why out; link to it.

Principles

• Address a real problem or goal — not a tool. Documentation that describes operating machinery ("to shut off the water, turn the tap clockwise") isn't a how-to guide; it doesn't help the user with what they're trying to do. Frame around the user's actual task ("how to stop a leak"), the way they would.
• Provide a logical sequence with flow. A how-to guide is a series of steps that must be followed in order. Ground the order in the user's natural pattern of activity so it flows; an ill-considered order is the most common how-to failure.
• Describe actions — including thinking and judgement, not only commands to type. Real tasks require decisions; say what to weigh, not just what to run.
• Don't explain. Concepts and background interrupt the work. If understanding is needed, link to an explanation.
• Accommodate the real world with conditional imperatives. Users arrive in different situations: "If you want x, do y. To achieve w, do z." Cover the practical variations they'll actually hit.
• Omit the unnecessary; favour usability over completeness. A how-to guide is not exhaustive. Practical usability beats comprehensiveness — leave out anything that doesn't serve the goal. (Completeness is reference's job.)
• Name it well. The title must say exactly what the guide shows. "How to integrate application performance monitoring" is good; "Monitoring" or "Performance" is not — the reader searching for a solution must recognise it instantly.

Keep out of a how-to guide

Language patterns

• Open with the goal: "This guide shows you how to…"
• Conditional imperatives for real-world variation: "If you want x, do y."
• Action-oriented titles naming the outcome: "How to {do the thing}".

Smell test

If a competent reader who knows their goal can't follow it straight to a result — because it stops to teach, explain, or list every possibility — it has drifted out of how-to.

Reference: https://diataxis.fr/how-to-guides/

Documentation Quality — what "good" means

When the workflow says assess it — "how well does this serve the need?" — these are the criteria. Diátaxis distinguishes two kinds of quality, and you check both.

Functional quality — measurable, objective

The constraints a document must meet to do its job at all. They are largely independent of each other, so each can be checked on its own:

• Accuracy — it is correct.
• Completeness — nothing the user needs is missing. (Remember: how-to guides and tutorials are deliberately not exhaustive — "complete" means complete for the need, not comprehensive. Exhaustiveness is reference's job.)
• Consistency — internally, and with sibling docs: same patterns, terms, and structure.
• Usefulness — it actually helps the user with the need it serves.
• Precision — exact and unambiguous.

Diátaxis cannot guarantee functional quality — that takes technical skill and domain knowledge. But it exposes lapses: when each page has exactly one job, missing or wrong content has nowhere to hide.

Deep quality — subjective, interdependent

The qualities that make documentation feel good to use. They can't be measured numerically, but they're unmistakable when present, and they're interdependent — they reinforce one another:

• It feels good to use; it has flow.
• It anticipates the user's needs — answers the next question before it's asked.
• It fits the human — there's a rightness, even a beauty, to it.

Deep quality is assessed against the human, not against an external spec — "your body knows it," the way you recognise a well-fitting garment without taking measurements. It rests on top of functional quality: you can't feel-good your way past inaccuracy.

What Diátaxis can and can't do for quality

• Exposes functional lapses, through structural clarity.
• Supports deep quality by organising content around user needs and sustaining narrative flow.
• Does not replace UX, interaction, or visual design — and does not, by itself, make content accurate.

Using this in an assessment

A two-pass check for any page:

1. Functional pass (objective): accurate? complete for its need? consistent? precise? useful? — any "no" is a defect to fix in place. 2. Deep pass (felt): does it flow? does it anticipate the next question? does using it feel good? — a "no" here usually traces back to a mode confusion or a functional gap. Run compass-tree.md; the fix is often a split (wrong-type-tree.md), not more polish.

Record both passes in ../assets/templates/report.md.

Reference: https://diataxis.fr/quality/

Reference — information-oriented

Reference guides are technical descriptions of the machinery and how to operate it. They are information-oriented: propositional, theoretical knowledge the user consults during work rather than reads through. Reference is like an encyclopaedia entry, or a map — it states the facts of the territory so the user can trust them without verifying for themselves.

Users come to reference for truth and certainty — a firm platform to stand on while they work. Reference is the one mode led by the structure of the product, not by the user's needs.

What makes reference different

• vs [how-to guide](how-to-guides.md): reference describes; a how-to instructs. Don't put step-by-step procedures in reference.
• vs [explanation](explanation.md): reference is neutral description; explanation is discursive, with context and opinion. No discussion, no argument, no "why" in reference — link out for that.
• It is consulted, not read. Optimise for finding the one fact, not for a narrative read-through.

The four principles

1. Describe, and only describe. Neutral description is the sole job. The style is austere and uncompromising; its virtues are accuracy, precision, completeness, and clarity. Resist every urge to instruct, explain, speculate, or offer opinion — link to the how-to or explanation that belongs to it instead. 2. Adopt standard patterns. Reference is useful when it is consistent. Put information where the user expects to find it; use the same structure for every like thing; prefer a familiar, repeated format over stylistic variety. Predictability is the feature. 3. Respect the structure of the machinery. The documentation's structure should mirror the structure of the product — the logical arrangement of the code, the API, the CLI. The map matches the territory, so users navigate it the way they navigate the thing itself. 4. Provide examples. Illustrate with examples — but examples that show, without explaining or instructing. A short, in-context snippet conveys usage faster than prose.

Keep out of reference

Language patterns

• Declarative statements of fact, not narrative: state what is.
• Lists of commands, options, fields, parameters, return values, limits, and errors.
• Warnings and caveats where the machinery can bite — stated plainly, not argued.

Smell test

If a reader can't open it, jump straight to the exact fact they need, and trust it without reading around it — or if it starts narrating, instructing, or editorialising — it has stopped being reference.

Reference: https://diataxis.fr/reference/

Decision Tree: Restructure a Messy Doc Set

Symptom: "our docs are a sprawling mess — where do I even start?" This tree is the Diátaxis workflow applied to a whole corpus. The core rule: do not restructure top-down. Use Diátaxis as a guide, not a plan.

A large, messy doc set
│
├── DON'T (the two failure modes):
│   ├── Create the four empty buckets (tutorials/, how-to/, reference/, explanation/)
│   │   and try to file everything at once. Empty structure with no content is worse
│   │   than no structure — "it's horrible," and the migration stalls half-done.
│   └── Tear it all down to "start fresh." You'll lose working content and ship nothing
│       for months.
│
├── Step 1. CHOOSE something small. One page, one section, even one paragraph —
│   preferably something you're already touching for another reason. Scope = tiny.
│   On a large corpus, triage first: run queries/scan-docs.sh <docs_root> to list
│   pages showing signals of two+ modes (candidate type-mixes) — pick from those.
│
├── Step 2. ASSESS it. Ask the two diagnostic questions:
│   "What user need does this represent? How well does it serve that need?"
│   Run the compass (compass-tree.md) and check quality (quality.md).
│   ├── Serves one need, serves it well → leave it. Return to Step 1 with the next thing.
│   ├── Serves the wrong mode, or mixes modes → go to wrong-type-tree.md.
│   └── A user need has no content at all → go to gaps-tree.md.
│
├── Step 3. DECIDE one next action that produces an immediate improvement — the
│   smallest useful change, not the ideal end-state.
│
├── Step 4. DO it, and PUBLISH immediately — even though the whole is still unfinished.
│   A small published improvement beats a big unpublished plan.
│
└── Step 5. REPEAT. Let overall structure EMERGE from the improving parts (organic
    growth that adapts to real conditions, not an imposed blueprint).
    Terminal each loop: ONE published improvement.

The standard you're holding to

The corpus is never "finished" — but at every moment it should be "complete": every part that exists is useful and structurally sound for its current stage of growth. Complete-not-finished is what lets you ship continuously without an empty-scaffold phase. See workflow.md for the full rationale.

Terminal actions

• Each loop ends in one published change. There is no "done" — there is only complete at this stage.
• Periodically run a full pass with ../assets/templates/report.md to see the shape that's emerging and pick the next worst gap.
• When a single piece needs classifying → compass-tree.md; mixing → wrong-type-tree.md; missing → gaps-tree.md.

Symptom Catalog

Each symptom is an entry point into a decision tree. Match the situation to a row, then open the tree. Severity reflects how badly the reader is failed right now — P1 means readers are blocked or actively misled today.

How severity maps to action

• P1 — Readers are blocked or failing right now (can't get started, can't complete a task). Fix the closed acquisition/goal path first; this is where users are leaving.
• P2 — Content exists but in the wrong mode or incomplete, creating friction and eroding trust. Separate it, or complete it.
• P3 — The corpus needs structural / meta work. Valuable, but improve it incrementally — never by tearing it down.

Terminal states (every tree ends in one)

1. Identify the mode — decide which of the four modes the content serves, and write/route it there. 2. Split — separate a mixed document into the single-mode pieces it was conflating; link them instead of inlining. 3. Create — write the missing mode that a failing user need points to. 4. Improve in place — apply one small workflow iteration and publish; let structure emerge. 5. Dismiss — the document is already single-mode and serving its need. No Diátaxis action (optionally hand prose issues to a copy-editing skill).

Audit history

When auditing an existing doc set, record findings with ../assets/templates/report.md and append a one-line entry per audit to the log (default ${CLAUDE_PLUGIN_DATA:-$HOME/.claude}/diataxis-audits.log, set in config.json). Over time this shows which gaps recur and whether splits actually held.

Tutorials — learning-oriented

A tutorial is a lesson: an experience that takes place under the guidance of a tutor. It is learning-oriented. A tutorial is a practical activity in which the learner learns by doing something meaningful, towards an achievable goal. It is to documentation what teaching a small child to cook is to feeding them.

A tutorial serves the user's acquisition of skill — their study. It does not serve getting a job done. The moment you start helping the reader accomplish their own task, you are writing a how-to guide.

What makes a tutorial different

• Responsibility is the tutor's, not the learner's. The learner follows; you guarantee they arrive somewhere meaningful. They are not yet in a position to make their own choices.
• It's measured by learning, not by output. Whatever gets built is a vehicle for the lesson — often throwaway. The point is the experience and the confidence it leaves behind.
• It does not "teach" in the lecture sense. Understanding emerges from doing, not from concepts delivered up front.

Principles

• Don't try to teach. Resist the urge to explain. A tutorial is not the place for explanation — explanation interrupts the doing and overwhelms the beginner. Allow the user to learn by doing; if you must, link out to an explanation.
• Get the learner doing things, fast. Show the destination early so they know where they're headed, then deliver visible results early and often. Each step should produce a meaningful, observable outcome.
• Maintain a narrative of expectations. Tell the learner what to expect — "You will notice that…", "The screen will now show…" — so they can confirm they're on track. Point out what they should observe.
• Target the feeling of doing. Aim for a pleasurable rhythm where purpose, action, and result line up. That feeling is what builds confidence and keeps the learner going.
• Be reliable. Always work. A tutorial that fails part-way destroys the learner's confidence in themselves. It must be repeatable and work every time, for everyone, on every supported system. This is the highest bar of any mode.
• Be concrete, not abstract. Work step-by-step through one specific example. Don't generalise; don't present the abstract principle the example illustrates — that's explanation.
• Ignore options and alternatives. Eliminate choices, diversions, and "you could also…". Maintain a single, confident path. Approach problems the learner doesn't even know they have by simply not creating them.

Keep out of a tutorial

Language patterns

• First-person plural — "we" — to affirm the tutor-with-learner relationship: "We're going to create…"
• Unambiguous, sequential directions: "First, do x. Now, do y."
• Clear statements of the expected result of each action.
• Confirmation cues: "Notice that…", "Remember that…", "You should see…".
• Celebrate accomplishment: describe what the learner has just built or achieved.

Smell test

If a beginner can't get started and succeed by following it top to bottom — or if it pauses to explain, branches into options, or assumes knowledge they don't have yet — it has stopped being a tutorial.

Reference: https://diataxis.fr/tutorials/

The Diátaxis Workflow — a guide to work

Diátaxis is a way to understand documentation, applied as a way to work on it. The whole method of improvement fits in one loop, run over and over at small scale.

Use Diátaxis as a guide, not a plan

Diátaxis describes what good documentation looks like; it does not hand you a project plan. It actively discourages top-down planning in favour of small, responsive iterations from which the overall pattern emerges. Don't wait to understand the whole framework before you start — apply each idea as you meet it, alternating between doing the work and reflecting on it.

Don't worry about structure first

The most tempting wrong move is to create the four empty containers — tutorials/, how-to/, reference/, explanation/ — with a skeleton of headings and no content. Empty structure is horrible: it advertises content that isn't there, and the migration stalls half-built. Structure should emerge from healthy parts, never be imposed ahead of them.

Work one step at a time

Improve wherever the opportunity is, at the smallest scale that's still useful — a section, a paragraph, a sentence. Then publish the change immediately, even if everything around it is still imperfect.

Just do something — the loop

   ┌─────────────────────────────────────────────┐
   ▼                                              │
1. CHOOSE something   ── any piece, preferably small
   │
   ▼
2. ASSESS it          ── "What user need does this represent?
   │                      How well does it serve that need?"
   ▼
3. DECIDE what to do  ── a single next action that produces
   │                      an immediate improvement
   ▼
4. DO it              ── complete the change, and PUBLISH it
   │
   └──────────────────── repeat

That's the entire workflow. Its power is that every pass leaves the docs better and shipped — there is never a long broken interlude.

Allow your work to develop organically

Good documentation grows like a well-formed organism that adapts to external conditions, not like a building erected to a fixed blueprint. When the internal parts are healthy — each serving one need well — the overall structure that emerges is sound. Trust that.

Complete, not finished

Documentation is never finished — but it should always be complete: at any given moment, everything that exists is useful to users and structurally sound for its current stage of growth. Holding to "complete, not finished" is exactly what lets you ship continuously and never need a big-bang reorganisation.

How this connects to the rest of the skill

• The assess step uses compass-tree.md (which mode is this?) and quality.md (how well does it serve the need?).
• The decide / do step routes through wrong-type-tree.md (content is mixed), gaps-tree.md (a need has no content), or the four type guides (tutorials, how-to-guides, reference, explanation) for how to write the chosen mode well.
• For a whole messy corpus, restructure-tree.md is this same loop applied at scale.

Reference: https://diataxis.fr/how-to-use-diataxis/

Decision Tree: Wrong Type / Type-Mixing

Symptom: a page feels bloated, rambling, or hard to use, or a mode has visibly drifted — a tutorial that stalls into explanation, a how-to guide that lectures, reference that editorialises, an explanation stuffed with steps. Almost every documentation problem is this one: content serving more than one need at once.

The fix is never to "balance" the modes inside one page — it's to separate them.

A document feels off / mixed
│
├── Step 1. Establish the document's PRIMARY job.
│   Run the compass on the document as a whole → compass-tree.md.
│   That one mode stays; everything that serves a different need is a candidate to move out.
│
├── Step 2. Scan for the four tell-tale intrusions and relocate each:
│   │
│   ├── Passages that EXPLAIN — "the reason is…", history, trade-offs, rationale
│   │   └── If primary mode ≠ explanation → MOVE to an explanation page; link to it.
│   │       See explanation.md.
│   │
│   ├── Passages that INSTRUCT step-by-step — "first do x, then y"
│   │   └── If primary mode ≠ how-to/tutorial → MOVE to a how-to guide; link to it.
│   │       See how-to-guides.md.
│   │
│   ├── Passages that exhaustively DESCRIBE — option tables, every flag/param/field
│   │   └── If primary mode ≠ reference → MOVE to reference; link to it. See reference.md.
│   │
│   └── A guided first-run LESSON embedded inside something else
│       └── MOVE to a tutorial; link to it. See tutorials.md.
│
├── Step 3. Resolve the two classic confusions deliberately:
│   │
│   ├── TUTORIAL vs HOW-TO (both inform action). Ask: is the reader a BEGINNER I'm
│   │   teaching (→ tutorial) or a COMPETENT user pursuing their own goal (→ how-to)?
│   │   Split the content along that line.
│   │
│   └── REFERENCE vs EXPLANATION (both inform cognition). Ask: is this NEUTRAL fact to
│       look up (→ reference) or DISCUSSION to build understanding (→ explanation)?
│       Split along that line.
│
└── Step 4. Verify and record.
    Each resulting page should now serve EXACTLY ONE need and LINK to its siblings
    instead of inlining them. Re-run the compass on each to confirm it's single-mode.
    Terminal: SPLIT complete — record it in ../assets/templates/report.md.

If nothing needs moving

If Step 1 shows the document is already single-mode and just reads badly (clumsy prose, poor ordering within the mode), this is not a Diátaxis problem.

• Terminal: DISMISS — hand it to prose/structure editing within its mode (e.g. a copy-editing skill), or fix flow using that mode's own principles. Don't split a page that has only one need.

Decision criteria