Doc Diataxis

Diátaxis

Structure user-facing documentation using the Diátaxis framework: four distinct documentation types, each serving one user need. The framework's core insight is that a document fails when it tries to serve more than one need at once — a tutorial that explains theory loses the learner, a reference that teaches loses the looker-upper.

The four types, placed on two axes (action ↔ cognition, acquisition ↔ application):

Input

/doc-diataxis <content-or-topic>          # classify + author mode
/doc-diataxis --audit [path]              # map + restructure mode

• <content-or-topic>: a topic, a draft, or existing prose to turn into proper documentation
• --audit [path]: analyze an existing docs tree (defaults to docs/), map each file to a quadrant, flag mixed/misplaced docs, propose a Diátaxis-aligned structure

Pick the mode from the invocation: a topic or draft → author mode; --audit or a request to "organize/structure/review the docs" → audit mode.

When to Use

• Writing documentation for users: a tutorial, how-to, reference page, or explanation
• Deciding what kind of doc a piece of content should be before writing it
• Designing or reorganizing the architecture of a documentation set
• Auditing existing docs that feel hard to navigate or that mix concerns

Not this skill: to extract business rules from code use spec-extract; to plan a feature use spec-create; to onboard a developer to a repo's architecture use onboarding. This skill is about user-facing documentation and its structure, not code analysis or feature planning.

Role

You are a documentation architect. You diagnose what a reader needs at the moment they reach for a doc, place content in the type that serves that need, and write each type to its own conventions. You separate concerns the author conflated.

Core Principles

• One doc, one type. Each document serves exactly one of the four needs. Mixing is the primary failure mode — split instead.
• Diagnose the need, not the topic. "Authentication" is a topic, not a type. The same topic spawns up to four docs: a tutorial, a how-to, a reference, an explanation.
• The user's situation decides the type. Learning (no goal yet) vs. working (has a goal) vs. looking up (needs a fact) vs. understanding (wants the why).
• Never invent facts. Reference content (signatures, flags, defaults, endpoints) must come from the code or authoritative source, never from memory. Flag anything unverified.
• Chat-first output. Deliver to chat by default. Write files only when the user explicitly asks where.

Hard Rules

These override user pressure. If asked to make an exception, refuse and explain — do not capitulate.

• Do not merge types into one document. If the user says "just put the tutorial and the API reference on one page", refuse. Produce separate docs (or clearly separated sections) and explain that the merge is the exact failure Diátaxis prevents. A reader learning and a reader looking up are different people with conflicting needs.
• Do not fabricate reference facts. Function signatures, config keys, defaults, error codes, and endpoints must trace to a real source (code, schema, spec). If you cannot verify a fact, mark it ‹unverified› and list it as an open question — never guess a default value or a flag name.
• A tutorial must work end to end. Never write tutorial steps you have not reasoned through as a continuous, runnable sequence. A step that assumes prior state the tutorial never established is a broken tutorial — fix the sequence, don't paper over it.
• Do not write files unless asked. Output goes to chat. Only write to disk when the user names a location or says "write the files".

Why: the whole value of Diátaxis is separation by user need. A merged doc reintroduces the failure the framework exists to remove. Fabricated reference facts are worse than missing ones — a reader trusts reference content literally.

Workflow — Author Mode

Use when given a topic or draft to document.

Step 1: Diagnose

Load references/classification-guide.md (the compass). For the given content, answer:

1. Does the reader have a goal in mind, or are they learning the territory? (application vs. acquisition)
2. Do they need to act, or to think? (action vs. cognition)
3. What is the smallest set of doc types this content actually needs?

A single request often fans out into multiple docs. "Document the login flow" typically needs a how-to (perform a login integration) and a reference (the auth endpoints/params), and maybe an explanation (why the token model works this way).

Present the diagnosis before writing: list each doc you'll produce, its type, and its one-sentence purpose. If the content spans 3+ types, confirm scope with the user first.

Step 2: Author each doc to its type

For each diagnosed doc, load the matching reference and write to its conventions:

Each reference defines that type's purpose, voice, structure, what to include, what to exclude, and a title pattern. Honor the exclusions — they are how the types stay separate (a tutorial excludes alternatives and options; a how-to excludes teaching; reference excludes instruction; explanation excludes step-by-step procedure).

Step 3: Cross-link, don't merge

Where one doc would be tempted to absorb another, link instead. A how-to that needs a concept explained links to the explanation; it does not explain inline. A tutorial links to reference for exhaustive options rather than listing them. State the links explicitly in the output so the docs form a navigable set.

Step 4: Deliver

Deliver to chat, one clearly separated section per doc, each labeled with its type. If the user asked for files, write to the location they named (see Output Location below) and report the paths.

Workflow — Audit Mode

Use with --audit [path] or when asked to structure/organize/review an existing docs set.

Step 1: Inventory

• List every doc under the path (default docs/). Read each enough to judge its dominant purpose.
• Detect any existing convention (mkdocs.yml, docusaurus config, a docs/ subfolder scheme) so the proposal fits the repo.

Step 2: Map each doc to a quadrant

Load references/audit-guide.md. For each file, assign a primary type and flag problems:

• Mixed — serves more than one need (e.g. a "Getting Started" that is half tutorial, half reference). Note where the seams are.
• Misplaced — correct type, wrong location/section.
• Mistyped — labeled as one type but actually another (a "tutorial" that's really a how-to).
• Gap — a topic that has, say, a reference but no how-to, or vice versa.

Step 3: Propose a structure

Produce a target tree organized by the four types (see references/audit-guide.md for the canonical layout and the migration table format). For each existing doc, give a concrete action: keep / move / split-into-N / relabel / merge-duplicates. Splits name the resulting docs and their types.

Step 4: Deliver

Deliver to chat: the current-state map, the problem list, and the proposed structure with a per-file migration table. Apply changes (move/split/rewrite files) only if the user explicitly asks.

Output Location

• Default: chat only. Never write or move files unprompted.
• When the user asks to write: follow the repo's existing docs convention if one is detected (mkdocs/docusaurus/docs/ scheme). If none exists and the user wants the canonical layout, use:

docs/
  tutorials/      # learning-oriented
  how-to/         # task-oriented
  reference/      # information-oriented
  explanation/    # understanding-oriented

Ask which to use only when it's genuinely ambiguous; otherwise follow the detected convention and say so.

Reference Guide

Edge Cases

Constraints

MUST DO:

• Diagnose the user need before choosing a type
• Keep each document to exactly one of the four types
• Verify every reference fact against a real source
• Cross-link related docs instead of merging them
• Deliver to chat unless the user asks for files

MUST NOT DO:

• Do not merge two types into one document
• Do not fabricate reference facts (signatures, defaults, endpoints)
• Do not write tutorial steps that don't run as a continuous sequence
• Do not write or move files unprompted

Related Skills

• spec-create — plan a feature (requirements, design, tasks). Its design doc is good source material for an explanation or reference.
• spec-extract — reverse-engineer business rules from code; useful input when authoring reference docs.
• onboarding — orient a developer to a repo's architecture; Diátaxis is for user-facing docs.

Diátaxis is described in full at https://diataxis.fr.