Diataxis framework skill

Documentation that fails users almost always fails by mixing modes — a tutorial that pauses to lecture, a reference that tries to teach, a how-to that demands you read three chapters first. Diataxis (https://diataxis.fr) is the framework that separates documentation into four distinct quadrants based on what the user actually needs in the moment, and it is the standard this repo applies to every documentation contribution.

This skill exists so any agent or contributor working on documentation in this org can:

1. Decide which quadrant a page belongs in without guessing.
2. Audit existing pages that drift across quadrants and split them.
3. Name and organize files consistently with the conventions every repo here enforces.
4. Recognize the common confusions (tutorial-vs-how-to is the worst offender) and avoid them.

If you are writing or reviewing documentation in this org and you have not classified the page against Diataxis, you have not finished the job.

Foundations — why exactly four

Diataxis is not a heuristic that "seems to work." It rests on the structure of craft itself, and the claim that there are exactly four quadrants — not three or five — is a derivation, not a convention.

The user a documentation set serves is a practitioner in a domain of skill. A domain of skill — using a programming language, flying an aircraft, operating a database — has two structural dimensions:

• Action vs cognition. Every craft contains practical knowledge (knowing how, what we do) and theoretical knowledge (knowing that, what we think). These are counterparts: distinct, but bound up in each other.
• Acquisition vs application. Every practitioner has two modes with their craft: acquiring it (study) and applying it (work). Also counterparts: distinct, but bound up.

Two dimensions, each binary → a 2×2 map of the territory of craft. The map is complete because those two dimensions cover everything: there is no third axis of craft and no fifth quadrant to fill.

The canonical diagrams are upstream at:

• The two dimensions of craft: https://diataxis.fr/_images/two-dimensions.png
• The four axes of user needs that map to documentation types: https://diataxis.fr/_images/axes-of-needs.png

Documentation aligned with this map serves four orthogonal user needs:

Need	Documentation type	The user is…	The doc informs…
Learning	Tutorial	acquiring their craft	action
Goals	How-to guide	applying their craft	action
Information	Reference	applying their craft	cognition
Understanding	Explanation	acquiring their craft	cognition

This is why the four-quadrant model is not arbitrary: it is the complete enumeration of orthogonal user needs in a craft. Anything that claims to be a fifth type is either a specialization (runbook, ADR, troubleshooting) that still maps to one of the four, or it is not documentation at all (marketing copy, release notes are reference-flavored, etc.).

Full theoretical treatment: references/foundations.md.

The compass — two axes, four quadrants

Diataxis classifies every page by answering two questions:

	Acquisition (study)	Application (work)
Action (doing)	Tutorial — learn by doing	How-to guide — accomplish a task
Cognition (thinking)	Explanation — understand a concept	Reference — look up a fact

Ask, in order:

1. Is the user engaged in action or cognition? Are they typing commands and watching outputs (action), or sitting back and absorbing ideas (cognition)?
2. Is the user in acquisition or application mode? Are they learning how things work (acquisition / study), or doing real work and consulting docs as they go (application / work)?

Two answers → one quadrant. If you cannot answer cleanly, the page is probably trying to do two jobs and should be split.

The four quadrants

Tutorial — learning-oriented (study + action)

A tutorial is a lesson. The reader is a learner who follows you step by step and learns by completing a guided activity. Every step produces a visible result the learner can verify. The tutorial author is responsible for the learner's success: bulletproof reliability, ruthless minimization of explanation, no choices or alternatives, narrate what to notice. The success criterion is what the learner acquires, not what they accomplish.

Filename convention: no prefix (topical, e.g. claude-code-setup.md). Deep dive: references/tutorials.md.

How-to guide — task-oriented (work + action)

A how-to guide is a recipe for an already-competent user who has a specific outcome in mind. It assumes they know the domain, addresses one real-world problem, and omits everything the user doesn't need to reach the goal. How-to guides are led by the user, structured around outcomes (not the machinery), and adaptable to the user's variations of the task. Success is task completion, not learning.

Filename convention: how-to- prefix (e.g. how-to-rotate-vault-tokens.md). Deep dive: references/how-to-guides.md.

Reference — information-oriented (work + cognition)

Reference material is the map users consult while working. It is led by the product, not the user. Its structure mirrors the codebase. It is austere, factual, consistent, complete, and accurate — but it does not teach, does not narrate, does not include opinion, and does not show how to perform tasks. Users do not read reference; they consult it.

Filename convention: ref- prefix (e.g. ref-cli-flags.md). Deep dive: references/reference-quadrant.md.

Explanation — understanding-oriented (study + cognition)

Explanation is the discussion that lets the user step back from work and reflect. It provides historical context, design rationale, trade-offs, and alternatives. It has permission to be opinionated and to make connections outside the immediate scope. It must remain bounded — it does not instruct, does not document features, and does not provide step-by-step procedures.

Filename convention: no prefix (topical, e.g. epic-on-azure-architecture.md). Deep dive: references/explanation.md.

How to use this skill

When writing a new page

1. State the user's situation in one sentence. "An SRE at 2am who…", "A new hire on day one who…", "A platform engineer trying to…". The sentence answers both compass questions.
2. Map to a quadrant via the compass table.
3. Pick the matching filename prefix and folder. Repos in this org typically organize by quadrant: tutorials/, how-tos/, references/, explanations/. Some megadoc repos use a flat docs/ with file-name prefixes only.
4. Write to the quadrant's discipline. Use references/<quadrant>.md in this skill as the rulebook. The most common slip is letting another quadrant bleed in — a tutorial sneaking in reference detail, a how-to drifting into teaching mode.

When auditing an existing page

1. Read the page top to bottom. What is it trying to be?
2. Find sentences that don't fit that goal. A tutorial with a "you could also…" alternative. A reference with a "here's why we chose this approach" paragraph. A how-to that opens with a 200-word history lesson.
3. Decide: split, move, or trim. Mixed content is the default failure mode; the fix is almost always to extract the off-quadrant material into its own page in the correct quadrant and cross-link.
4. Update the filename and doc_type frontmatter to match. The Diataxis prefix and the YAML doc_type are the contract — if either is wrong, downstream agents will trust the wrong category.

Deep workflow: references/workflow.md (the iterative, organic approach Diataxis itself recommends — not a big-bang audit).

Concrete tests for "which quadrant?"

Test	Tutorial	How-to	Reference	Explanation
Can the reader follow it on their first day?	yes	only if competent	yes (they consult)	yes (they read)
Does every step produce a visible result?	must	should	no	no
Does it document the machinery or the user's task?	task	task	machinery	machinery
Are alternatives / options discussed?	never	sometimes	listed	yes
Should the reader be able to repeat it identically?	yes	yes	n/a	n/a
Does it end where the user's job ends, not where the feature ends?	yes	yes	no	no
Title implicitly fits "About __"?	no	no	no	yes

Common confusions (and how to detect them)

1. Tutorial vs how-to is the #1 source of bad docs. Diataxis itself: "How-to guides are wholly distinct from tutorials. They are often confused, but the user needs that they serve are quite different. Conflating them is at the root of many difficulties that afflict documentation." If the page assumes prior competence and the reader has a specific outcome in mind → how-to. If the page is teaching the domain through guided practice → tutorial. Most pages labelled tutorial-* in legacy docs are actually how-tos.
2. Reference creeping in. Reference sections inside tutorials and how-tos break the user's flow. Extract them and link out. Symptom: long flag tables, exhaustive option lists, "see also: every related setting".
3. Explanation in disguise. "Why we chose Postgres" inside a how-to about backing up Postgres. The how-to should link to the explanation, not embed it. Symptom: paragraphs beginning with "Historically…", "We chose this because…", "There are two schools of thought…".
4. Tutorials that aren't reproducible. If the example role, dataset, or environment doesn't exist or the agent output is "illustrative", the page is a narrated walkthrough (closer to explanation) — not a tutorial. Either ship a sandbox or reclassify.
5. Reference written as a narrative. Reference is consulted, not read. If it has a beginning/middle/end and a tone, it has drifted into explanation.

references/anti-patterns.md catalogues each pattern with a fix recipe.

Filename and frontmatter contract

Most ohemr / otc / cds megadocs enforce this:

---
title: Page title in sentence case
description: One-line summary used by search and the site index
owner: team-name
lifecycle_status: active        # active | draft | deprecated
last_reviewed: 2026-05-11
tags:
  - relevant-tag
doc_type: how-to                # tutorial | how-to | reference | explanation
                                # | concept | runbook | troubleshooting | adr
---

doc_type and the filename prefix must agree:

doc_type	Filename prefix
tutorial	(no prefix; topical name)
how-to	how-to-
reference	ref-
explanation	(no prefix; topical name)
concept	concept- (treated as explanation)
runbook	runbook- (operationally-flavored how-to)
troubleshooting	ts- (problem-solving how-to)
adr	adr-YYYYMMDD- (architectural-decision explanation)

runbook, troubleshooting, concept, and adr are Diataxis-compatible specializations the megadoc family uses for higher-fidelity classification — they all map back to one of the four quadrants.

Full mapping rationale: references/file-naming.md.

When NOT to invoke this skill

• For docs in third-party submodules you don't own — flag the issue upstream, don't restructure.
• For ADRs that already follow an ADR template — the template is the discipline; Diataxis just confirms the quadrant.
• For draft material the author has explicitly marked as a working scratchpad. Classify when it stabilizes.
• For README files at repo root — those serve a different audience (repo browsers) and use different conventions. They are not part of the docs tree.

Sources

• https://diataxis.fr — the canonical framework
• https://diataxis.fr/tutorials/
• https://diataxis.fr/how-to-guides/
• https://diataxis.fr/reference/
• https://diataxis.fr/explanation/
• https://diataxis.fr/compass/
• https://diataxis.fr/how-to-use-diataxis/

This skill is a practitioner's distillation of Diataxis for the otc megadoc family. When in doubt, the canonical source wins.