Diataxis documentation modes

Contract

Enforces the Diataxis rule that every documentation page occupies exactly ONE of four modes and never blends them. Apply when writing or organizing docs: first decide which single mode the need calls for, then write only that mode. A need that spans modes is split into separate documents, not merged into one hybrid page.

Rules

There are four modes. Each serves a different user in a different situation, and each is written differently. Pick one per document.

1. Tutorial — learning-oriented. A lesson that takes a beginner, by the hand, through a sequence of

concrete steps to a single guaranteed working result. The author takes full responsibility for the outcome; the learner just follows along. It has ONE path — no alternatives, no "you could also", no catalog of options. It teaches by doing, not by explaining: keep the theory to an absolute minimum.

1. How-to guide — goal-oriented. Directions that take an already-competent user through the steps to

accomplish one specific real-world goal ("how to do X"). It assumes prior knowledge, may branch on the user's situation ("if you use Y, do Z instead"), and includes only what the goal requires. It does NOT teach concepts, does NOT walk a beginner from zero, and does NOT explain the background theory.

1. Reference — information-oriented. A dry, factual, exhaustive description of the machinery: the

options, fields, flags, endpoints, parameters. It describes and only describes. Structure it to mirror the product (e.g. grouped by module, or alphabetical), keep it austere and consistent, and include NO step-by-step instructions, NO tutorials, NO opinions or recommendations.

1. Explanation — understanding-oriented. A discursive discussion that deepens understanding of a

topic: the why, the context, the design decisions, the trade-offs, the alternatives considered. It is read away from the keyboard. It gives NO step instructions and is NOT tied to completing a task.

1. One mode per document — never blend. The core rule. A page that opens with a beginner lesson, then

lists every configuration option, then discusses the architecture is FOUR documents crushed into one. When a need clearly spans modes, produce separate documents — a tutorial, a how-to, a reference, and an explanation — each pure, rather than a single hybrid page.

1. Match the shape to the mode. Tutorial and how-to are step sequences; reference is a described

listing; explanation is prose. A tutorial reads "First we will ...", a how-to "To achieve X, ...", a reference "timeout (integer, default 30): ...", an explanation "The reason we ... is ...".

Worked examples

The blended default is on the left; the single-mode conforming form on the right.

A brand-new user of a note-taking app:

BEFORE  One page: a walkthrough to create a first note, THEN a table of every sync
        setting, THEN a section on why the sync engine uses conflict-free merges.

AFTER   A tutorial ONLY: "First we'll create a note, then we'll watch it sync to a
        second device." One path, one guaranteed result. The settings table and the
        merge-engine discussion move to their own reference and explanation pages.

A competent user with a specific goal:

BEFORE  "Exporting your data" opens by teaching what a data model is and why exports
        matter, then finally gives the three steps to export to CSV.

AFTER   A how-to ONLY: "To export a project to CSV: 1. Open the project. 2. Choose
        Export. 3. Pick CSV." No beginner teaching, no motivation essay -- just the
        steps for someone who already knows the product.

A settings listing:

BEFORE  Each option is introduced with "you'll probably want to set this to...",
        mixing recommendations and a mini how-to into the description.

AFTER   Reference ONLY: "retry.max (integer, default 3): number of retry attempts.
        retry.backoff (seconds, default 1): delay between attempts." Dry, factual,
        no advice, no steps.

A "why" question:

BEFORE  A page titled "Understanding the scheduler" that is actually a step-by-step
        set-up guide with a paragraph of rationale wedged in the middle.

AFTER   Explanation ONLY: a discussion of why the scheduler uses a priority queue,
        what it trades off, and the alternatives weighed -- and no setup steps at all.

Edge cases & exceptions

• The ask is broad ("write the docs for feature X"). That is a request for a doc set, not one page.

Split it: a tutorial to learn the feature, a how-to per real task, a reference for its surface, an explanation of its design. Never answer a broad ask with one blended page.

• A tutorial needs a fact. State the minimum inline and link to the reference page for the full detail

rather than pasting the whole options table into the lesson.

• A how-to touches on "why". One sentence of motivation is fine; a paragraph of theory means the

content belongs in an explanation page instead.

• Truly tiny projects. Even a single README keeps its modes in separate sections — a getting-started

lesson, a usage how-to, a reference block — rather than interleaving them line by line.

Do / Don't

• Do decide the single mode before writing. Don't start typing a page that is "documentation" in general.
• Do keep a tutorial to one guaranteed path. Don't offer alternatives or optional detours inside it.
• Do assume competence in a how-to. Don't restart from beginner concepts.
• Do keep reference dry and factual. Don't slip in recommendations, tutorials, or rationale.
• Do keep explanation free of step instructions. Don't turn it into a setup guide.
• Do split a cross-mode need into separate documents. Don't merge them into one hybrid page.

Common mistakes

• The all-in-one page: teach + steps + options table + architecture discussion in one document.
• A tutorial that forks into "you could also ..." options and stops guaranteeing a result.
• A how-to that teaches beginner concepts before getting to the goal's steps.
• Reference entries padded with advice ("you'll usually want ...") or a mini walkthrough.
• An explanation page that is secretly a how-to with a rationale paragraph bolted on.

Quick checklist

• The document is exactly ONE of: tutorial, how-to, reference, explanation.
• A tutorial has one path to one guaranteed result, minimal theory.
• A how-to assumes competence and gives only the goal's steps.
• Reference is dry, factual description with no steps or advice.
• Explanation discusses the why with no step instructions.
• A cross-mode need is split into separate documents, not blended.