Diátaxis Docs Taxonomy
Mandate for documentation taxonomy across Datarim-managed repos and product sites: four orthogonal categories (tutorials, how-to, reference, explanation), closed mapping table, exemption list, anti-pattern definitions. Loaded by /dr-init, /dr-optimize audit, /dr-archive surface verification.
Overview
Diátaxis Docs Taxonomy is the source-of-truth contract for documentation structure across the Arcanada ecosystem. Every Datarim-managed repo and product site must organize its documentation into exactly four orthogonal categories: tutorials, how-to, reference, and explanation. No new top-level categories may be introduced. All content types, including FAQ, glossary, troubleshooting, examples, and overview, must map into one of the four canonical categories. The mandate is stack-agnostic — any static site generator may be used as long as the taxonomy contract is respected.
The Four Categories
- Tutorials — Learning-oriented category for beginners. Reader intent: acquire foundational knowledge through guided step-by-step experience. Typical content: getting-started guides, walkthroughs, interactive lessons, first-application tutorials. The reader does not yet know what questions to ask.
- How-to — Task-oriented category for practitioners. Reader intent: solve a specific problem or complete a concrete task. Typical content: deployment guides, testing recipes, debugging instructions, configuration steps. The reader knows what they want to do and seeks precise instructions.
- Reference — Information-oriented category for lookup. Reader intent: find exact parameters, API signatures, configuration keys, or specification details. Typical content: API documentation, command-line flags, configuration schema, glossary, data types. The reader needs accurate and complete factual information.
- Explanation — Understanding-oriented category for deep comprehension. Reader intent: understand why something works the way it does. Typical content: architectural overviews, design decisions, conceptual background, tradeoff analysis, comparisons. The reader seeks mental models and contextual understanding.
Repo Bootstrap Layout
<project-root>/docs/
├── tutorials/
│ └── README.md
├── how-to/
│ ├── README.md
│ ├── testing.md (*)
│ ├── deployment.md (*)
│ └── gotchas.md (*)
├── reference/
│ ├── README.md
│ └── architecture.md (*)
├── explanation/
│ └── README.md
├── ephemeral/ (transient working material)
│ ├── plans/
│ ├── research/
│ └── reviews/(*) — legacy stubs auto-mapped from pre-mandate flat scaffold. Idempotency rule: each file or directory is created only if it does not already exist.
Mapping Table
| Legacy or proposed type | Diátaxis category | Rationale |
|---|---|---|
| architecture (default) | reference | Information-oriented — describes system structure |
| architecture (why) | explanation | Understanding-oriented — design decisions, tradeoffs |
| testing | how-to | Problem-solving — how to run tests, configure CI |
| deployment | how-to | Problem-solving — how to deploy the application |
| gotchas | how-to | Problem-solving — what to do when typical errors occur |
| api | reference | Information-oriented — lookup documentation |
| cli | reference | Information-oriented — command signature and flags |
| config | reference | Information-oriented — configuration schema and keys |
| concepts | explanation | Understanding-oriented — conceptual background |
| design | explanation | Understanding-oriented — design rationale |
| tutorial | tutorials | Learning-oriented — first end-to-end experience |
| quickstart | tutorials | Learning-oriented — minimal guided setup |
| faq | how-to or explanation (split) | Procedural items to how-to; conceptual background to explanation |
| troubleshooting | how-to | Problem-solving — what to do when something breaks |
| examples | how-to or reference | Task-driven examples to how-to; catalogue examples to reference |
| glossary | reference | Information-oriented — definitions |
This is a closed set. No new documentation types may be introduced as separate top-level categories.
Anti-Patterns
- FAQ as fifth category. FAQ is a conglomerate of how-to (problem-solving) and explanation (background). Mitigation: split FAQ entries into appropriate categories with cross-links.
- Examples as fifth category. Examples are either task-driven (how-to) or catalogues (reference). Mitigation: place each example in its semantic category with explicit context.
- Architecture always as reference. Architecture content that describes design decisions, tradeoffs, and reasoning must live under explanation/. Mitigation: evaluate reader intent — facts lookup or deep understanding.
- Index page as separate category. docs/index.md is optional entry-point, not a documentation type. Mitigation: index is navigation aid, not container for content.
- Troubleshooting as separate category. Troubleshooting content is purely how-to. Mitigation: place under how-to/ with clear problem-description titles.
- Cross-category content drift. Over time content may accumulate material from other categories. Mitigation: during reviews check each file against its category definition and split if necessary.
Exemption List
- Research-only repos (no user-facing documentation required).
- Archive-only repos (snapshots, backups, historical records).
- Obsidian vaults using PARA structure.
- Single-file inbox notes or scratch documents (ephemeral, non-public).
- Legacy repos created before mandate soft-approval date.
- Temporary scratch paths (temp/*, scratch/*, test-scaffold/*).
Operator override: any repo may be explicitly marked as intentional exemption in the exemption registry.
Stack-Agnostic Boundary
This mandate MUST NOT name any specific SSG or CMS (Docusaurus, Mintlify, VitePress, Hugo, Sphinx). The choice of document generator is per-project and outside the scope of the taxonomy mandate.
Slogan Compliance
Every updated public site in the ecosystem must display the slogan in a conspicuous location (footer, header, or splash page). Slogan compliance is verified during /dr-publish workflow and /dr-archive surface scan.
Drift Detection
Mandate compliance is verified by /dr-optimize Step 6 using a filesystem-presence check. Detection is soft — warning only, no build-blocking. A future hard CI gate (enforceable exit code 1) is deferred to an INFRA-* backlog item, to be activated after mandate adoption on at least three live consumers.