Diataxis

Diátaxis — classify, write, audit

Diátaxis's claim: documentation fails when one page serves two masters. Every doc serves exactly ONE of four needs, derived from two axes — is the reader acquiring skill (study) or applying it (work)? do they need action (practical steps) or cognition (knowledge)? One doc, one quadrant, always; other modes are LINKS, never inlined sections.

Provenance: the compass and the four contracts quote/paraphrase diataxis.fr (Procida); the SMELLS lists, the entry template, the audit, and the writing procedure are THIS SKILL's operationalization — useful, but do not cite them as Diátaxis. (Diátaxis is the needs-grounded, iterative successor of the older Divio four-types system.) Foundation the method stands on: documentation serves USER NEEDS, not the machinery — the four types enumerate practitioner needs: tutorials answer "can you teach me to…?", how-tos "how do I…?", reference "what is…?", explanation "why…?".

The compass (two questions, one quadrant — a doubt-resolver, applicable to a whole doc OR a single sentence)

The source's own use: reach for it "when you think you are doing one thing but are troubled by doubt" — at document, section, or sentence level. If a doc can't answer both questions, it has no single reader (splitting it is this skill's procedure, not a source rule). Mixed modes blur toward map-NEIGHBOURS (tutorial↔ how-to, how-to↔reference, reference↔explanation, explanation↔tutorial) — the sharpest mixed-mode predictor.

The four contracts (hard rules, per quadrant)

Tutorial — a lesson: the reader learns by DOING, and YOU own their success

• The reader is a beginner at THIS thing; you are the teacher and their success is your responsibility. One concrete path, start to visible result.
• RULES: deliver visible results early and often; concrete and particular, not general and abstract; "ignore options and alternatives" (source's words) — one path, no branches; minimum necessary explanation, link to Explanation instead; must work every time for every reader (our test method: run it cold); first-person plural ("we are in this together"); keep a narrative of expectations ("You will notice that…"); encourage and PERMIT repetition — "sometimes it's the only teacher".
• SMELLS: paragraphs of why; configuration choices offered; "you may want to"; steps that assume prior setup the tutorial didn't do.

How-to guide — a recipe: a COMPETENT user has a GOAL, get them to it

• The reader already has the skill; they have a real-world task NOW.
• RULES: name it "How to " (the goal, not the tool); a SEQUENCE of actions addressing the task, including its real-world variance (unlike a tutorial, forks for real conditions are fine); assume competence — no teaching, no concept-building; omit everything not needed for THIS task; completeness is measured by the task, not the machinery.
• SMELLS: defining terms; explaining internals; covering every option "for completeness"; starting from installation when the goal is elsewhere.

Reference — a map: austere, complete FACTS about the machinery

• The reader is working and needs to LOOK SOMETHING UP; certainty and consistency are the product.
• RULES: describe, never instruct and never explain; structure mirrors the structure of the PRODUCT (code-mirroring is the auto-generated special case); consistent, standard patterns per entry (a uniform template like signature · description · constraints · examples is OUR operationalization); examples are encouraged as illustration; "wholly authoritative — truth and certainty, firm platforms on which to stand"; austere, neutral; auto-generation from source is a powerful way to keep it faithful.
• SMELLS: "you should"; step sequences; design rationale; entries that exist only for some exports; prose that varies format entry to entry.

Explanation — understanding: the WHY, read away from the keyboard

• The reader wants the bigger picture: design decisions, context, alternatives, connections, history. The only quadrant where opinion and discussion belong.
• RULES: admit perspective ("the reason this is shaped so…"); make connections (to other parts, to prior art, to rejected designs); no instructions, no obligation to be complete; the source's test — the only docs it might make sense to read IN THE BATH, away from the product. (Our house addition, not Diátaxis: end at a real decision or trade-off — teaching without a point is a tour.)
• SMELLS: step-by-steps; API tables; pretending neutrality about a choice the project deliberately made.

The audit (executable — run over an existing doc set)

For each doc under the target path, as parallel checks (a Workflow fan-out for large sets; direct reads for small ones):

1. Classify: which quadrant does its title/frontmatter CLAIM? Which does the compass actually assign? Mismatch = finding.
2. Mixed-mode detection, by marker: instruction verbs + numbered steps in Reference; rationale/"because"/design-history paragraphs in Tutorials and How-tos; API signatures/exhaustive tables in Explanation; options and branches in Tutorials. Each hit: quote the passage, name the quadrant it belongs to, propose the split (extract + cross-link — never delete the content).
3. Coverage: for each major component in scope, which quadrants EXIST vs are MISSING — grounded in the map's "cycle of interaction": users mature from study to work and back, so reference-only fails newcomers and tutorial-only fails practitioners. Report the grid; per the process rule above, the grid PRIORITIZES, it does not mandate filling every cell.
4. Disposition per Diátaxis's OWN process rule — the method "is not a plan": improve organically, in small responsive iterations; never create empty quadrant structures to fill later; every step in the right direction is worth publishing immediately. So: fix the worst blur first, one doc at a time; "recorded, next iteration" IS a valid disposition here (unlike code review) — but silent acceptance still isn't. Docs are "always complete, never finished".

Project overlay

Read .agency/diataxis.md if it exists: where each quadrant LIVES in this project (paths, site sections, frontmatter conventions), plus any project rules. Missing overlay → classify/audit generically and SAY so.

Writing procedure (every new doc)

1. Run the compass; state the quadrant (frontmatter or the doc's one-liner).
2. Write to that quadrant's contract; when another mode wants in, LINK to it.
3. Self-audit against the quadrant's SMELLS list before declaring done.