The diataxis-docs Skill — Four Categories, No Exceptions
How the diataxis-docs skill enforces the Diátaxis taxonomy across every Datarim-managed repo, mapping every documentation type to one of four orthogonal categories and blocking the anti-patterns that erode it over time.
Documentation tends to accumulate a category for every type of content: a FAQ page, an examples page, a troubleshooting page, and eventually a page for things that don't fit anywhere else. The diataxis-docs skill enforces a different approach: four categories, each defined by reader intent, and a closed mapping that assigns every documentation type to exactly one of them.
The four categories
Tutorials are learning-oriented. The reader is a beginner who does not yet know what questions to ask and needs a guided end-to-end walkthrough to build foundational knowledge. How-to guides are task-oriented: the reader knows what they want to do and needs precise instructions to complete a specific, concrete task. Reference material is lookup-oriented: API signatures, configuration keys, command flags, and exact parameter values. Explanation is understanding-oriented: design decisions, architectural tradeoffs, and conceptual background that helps the reader build a mental model of why the system works the way it does.
The distinction between reference and explanation is a common source of confusion. Architecture content can go either way. If the reader looks up facts about the system's structure, the content is reference. If the reader seeks to understand the reasoning behind the structure, the content is explanation. The skill makes this call explicit with a mapping table.
The repo layout
Every new repo scaffolded under Datarim gets a docs/ directory with four subdirectories: tutorials/, how-to/, reference/, and explanation/. Each contains a README.md stub. An optional ephemeral/ directory holds transient working material — plans, research notes, and reviews — which are not documentation and do not need a Diátaxis category. The bootstrap is idempotent: directories and files are created only if they do not already exist.
The skill is stack-agnostic by design. It names no static site generator and no CMS. The taxonomy is the mandate; the tooling choice belongs to each project.
Anti-patterns the skill blocks
Six specific anti-patterns appear in the skill. FAQ as a fifth category is one: FAQ entries are either how-to (procedural steps) or explanation (background context), and the right fix is to split them, not to add a category. Examples as a fifth category is another: task-driven examples belong in how-to, catalogue examples belong in reference. A third is treating all architecture content as reference — design decision content that explains reasoning belongs in explanation.
The drift detection built into /dr-optimize Step 6 checks that all four directories exist and that at least three documentation files are present. The check is soft — it warns but does not block builds. A future hard CI gate is listed in the backlog for activation after the mandate reaches at least three live consumers.
Exemptions
Research-only repos, archive-only repos, Obsidian vaults using PARA structure, and legacy repos created before the mandate's soft-approval date are exempt. An operator may also mark any repo as explicitly exempted in datarim/docs/exemptions.json, which removes it from drift detection until the override is revoked.
The canonical specification this skill implements is the public Diátaxis framework at diataxis.fr. Read what Datarim is for the broader project context, or the /dr-optimize command post for where the drift detector sits in the audit workflow.