About Diataxis

This site organizes its documentation using the Diataxis framework. If you are writing or reviewing content for the megadoc, you should understand the four quadrants and which one your page belongs in before you start typing. This page is the in-site reference; the canonical sources on diataxis.fr remain the source of truth.

---

The framework in two sentences

Diataxis classifies every piece of technical documentation into exactly four types using two axes: action vs. cognition (is the reader doing something or thinking about something?) and acquisition vs. application (are they learning the product or using it at work?). Those two axes produce four quadrants — tutorial, how-to guide, reference, and explanation — and every doc fits in exactly one of them.

!!! abstract "Why this matters here" Megadoc aggregates ~74 submodules and hundreds of first-party pages. Without a shared classification, the site becomes a soup of "documents". Diataxis gives every author and reviewer the same vocabulary so a page about, say, AWX inventories can be unambiguously triaged as how-to (do a task), reference (look up a field), or explanation (understand the concept).

---

The two-axis compass

The canonical compass diagram is at diataxis.fr/_images/two-dimensions.png and the user-needs version at diataxis.fr/_images/axes-of-needs.png. See diataxis.fr/compass/ for the interactive walk-through.

The two dimensions are independent. They cross. That is why there are four quadrants — not three, not five.

---

The four quadrants

Tutorial — learning-oriented

A tutorial is a guided lesson. It takes a newcomer by the hand and walks them through a meaningful first experience of the product. The author chooses the path; the learner trusts and follows. Success is measured by what the learner now feels they can do, not by what they "know". Tutorials must work — the steps must succeed every time on every supported environment. Onboarding pages under getting-started/ are tutorials.

How-to guide — task-oriented

A how-to guide helps a competent user solve a specific real-world problem they brought with them. The user knows what they need ("rotate the Azure SPN", "publish a TFE module"); the guide assumes that competence and gets them to the answer. How-to guides do not teach — they assume the reader can already drive the tools and just needs the right sequence of steps for their situation. Pages in guides/ and most runbooks under operations/ are how-to guides.

Reference — information-oriented

A reference is the technical description of the machinery — schemas, API surfaces, configuration keys, naming standards, tag taxonomies. It is consulted, not read. Its single purpose is accuracy and structure; it does not teach, does not tell stories, does not discuss design alternatives. Pages in best-practices/, the schemas in infrastructure/, and the rules in getting-started/rules/ are references.

Explanation — understanding-oriented

An explanation discusses a topic so the reader understands why the system is the way it is. It can include history, design alternatives that were rejected, trade-offs, and the conceptual model behind the implementation. Architecture decision records (ADRs in the ohemr-arch-hub submodule) and conceptual write-ups belong here. This page is itself an explanation.

---

Why exactly four

Mixing two quadrants on one page is the dominant failure mode of technical documentation. Diataxis exists to make that failure visible.

---

How this site applies Diataxis

The megadoc nav (mkdocs.yml) groups pages by topic, not by quadrant, but each landing area has a dominant quadrant:

When in doubt, ask: what is the reader trying to do right now? Tutorials, how-tos, references, and explanations each answer that differently — and a single page can only honestly answer one.

---

File-naming convention

The file-name prefix encodes doc_type so a reviewer can classify a page from the file listing alone. Stage 1 of the docs-quality-check.yml workflow enforces this for new content.

Start any new page from the matching template in docs/templates/. The template's frontmatter and section headers are already correct for its quadrant.

---

Common confusions

See diataxis.fr/how-to-use-diataxis/ and diataxis.fr/complex-hierarchies/ for more pitfalls and recovery patterns.

---

When in doubt

• Deep practitioner reference — the otc-awesome-llm repo ships a shared/skills/diataxis-framework/ skill with per-quadrant deep-dives, an anti-pattern catalogue, and a content-audit workflow. Use it when you are auditing existing pages or refactoring a section of the site.
• Canonical sources — defer to diataxis.fr for the authoritative definition of each quadrant: tutorials, how-to guides, reference, explanation, the compass, the foundations, how to use Diataxis, and complex hierarchies.
• Templates — start from docs/templates/ rather than copying an existing page. The templates encode each quadrant's required sections.

---

For agents

Documentation-related agents (notably drzero:documentation and documentation-bot) automatically invoke the otc-awesome-llm shared/skills/diataxis-framework/ skill during reviews. That skill is the operational rulebook those agents apply when they classify a page, flag mis-categorisation, or propose splits. This page is the human-facing distillation of the same framework — the two stay aligned so authors and reviewing agents share one model of "what kind of doc is this?".

---

See also

• Writing Standards — site-wide style and frontmatter rules
• Style Guide — voice, headings, code-block conventions
• Contributing Overview — how to land a change in the megadoc
• Templates — per-quadrant starter files