mgajewskik/diataxis

Diátaxis

Use Diátaxis as a practical guide for documentation decisions, rewriting, and drafting.

The framework is about user need first. Decide what kind of help the reader needs, then write in the form that serves that need.

Purpose / Not For

Use this skill to:

• learn what Diátaxis is and why it works
• classify a page, section, or sentence as tutorial, how-to, reference, or explanation
• diagnose mixed-mode documentation and recommend the smallest clean split or rewrite
• reformat existing documentation into clearer Diátaxis-aligned shapes
• draft new documentation in the right Diátaxis mode
• reason about documentation hierarchy, landing pages, and organic restructuring

Out of scope by default:

• proving technical accuracy, completeness, or product correctness on its own
• forcing every documentation set into four empty top-level folders
• choosing document type based on topic difficulty, audience seniority, or vibes alone
• treating the older Divio presentation as the canonical source

Archetype

Recommend Complex with a compass-based router.

Why:

• users may want theory, classification, audit/reformatting, or drafting
• the same framework powers all modes, but each mode needs different instructions
• progressive loading matters because each quadrant has distinct writing rules and failure modes

Canonical Source Rule

• Treat https://diataxis.fr/ as canonical.
• Use documentation.divio.com only when the user explicitly asks for history or comparison, and mark it as an older, partially superseded presentation.
• Use the GitHub repository only for source/citation context, not to override the rendered site.

Load references/theory-quality-and-sources.md when source authority, history, or theory matters.

Mode Router

Detect the job first. If the request spans multiple modes, start with classify, then continue.

• learn-or-explain

  • Trigger: what is Diátaxis, why does it work, teach me the framework, explain tutorials vs how-to, explain reference vs explanation.
  • Load: references/compass-and-core.md
  • Load: references/theory-quality-and-sources.md when the question is about theory, quality, source authority, history, or why the framework claims four forms.
  • Load the relevant quadrant file when the question is type-specific.

• classify

  • Trigger: what kind of documentation is this, which quadrant does this belong in, tutorial or how-to, reference or explanation.
  • Load: references/compass-and-core.md
  • Load: references/distinctions-and-failure-modes.md
  • Load the most likely quadrant files only if the edge case needs deeper guidance.

• audit-or-reformat

  • Trigger: review this documentation, convert this to Diátaxis, reformat existing docs, fix mixed documentation, split this page by Diátaxis.
  • Load: references/compass-and-core.md
  • Load: references/audit-and-restructure.md
  • Load: references/distinctions-and-failure-modes.md
  • Load the source and target quadrant files that match the material being changed.

• draft

  • Trigger: write a tutorial, write a how-to, write reference docs, write explanation, draft docs in Diátaxis style.
  • Load: references/compass-and-core.md
  • Load the chosen quadrant file.
  • Load: references/distinctions-and-failure-modes.md if the request risks blending modes.

• architecture-or-hierarchy

  • Trigger: reorganize docs, design information architecture, structure landing pages, handle complex hierarchies, multi-audience docs.
  • Load: references/compass-and-core.md
  • Load: references/audit-and-restructure.md
  • Load: references/theory-quality-and-sources.md when the why behind the structure matters.

Core Decision Rule

Use the Diátaxis compass before making or revising documentation:

1. Does this content primarily inform action or inform cognition?
2. Does it primarily serve the reader’s study or work?

Mapping:

• action + study = tutorial
• action + work = how-to guide
• cognition + work = reference
• cognition + study = explanation

If the content mixes answers, treat that as a signal to split, move, trim, or rewrite — not as a reason to blur the categories.

Global Rules

• Decide document type from the reader’s need, not the writer’s topic list.
• Preserve clean boundaries between quadrants. Link out instead of stuffing other modes into the page.
• Use the smallest useful improvement step. Diátaxis is a guide for iteration, not a top-down migration plan.
• Do not create empty tutorial / how-to / reference / explanation shells just to satisfy the diagram.
• Complex hierarchies are allowed. Four documentation types do not mean exactly four top-level sections.
• Functional quality still matters. Diátaxis improves fit, flow, and clarity, but it does not by itself prove accuracy or completeness.
• When intuition and the compass disagree, trust the compass.
• For audits, classify at the smallest level that changes the decision: sentence, paragraph, section, page, or hierarchy.

Output Contract

• learn-or-explain

  • explain the chosen distinction or principle plainly
  • include the compass reasoning when relevant
  • name the next most useful reference to load

• classify

  • return the most likely quadrant
  • show the action/cognition and study/work reasoning
  • name the strongest conflicting signals, if any

• audit-or-reformat

  • identify the current dominant mode or mixed modes
  • call out boundary violations
  • recommend the smallest concrete restructuring moves
  • rewrite only as far as needed to fit the target mode cleanly

• draft

  • state the chosen quadrant briefly
  • draft in the language and structure of that quadrant
  • avoid importing content from neighboring quadrants unless clearly linked out

• architecture-or-hierarchy

  • recommend a user-first structure
  • explain why it fits Diátaxis without pretending the framework demands only one hierarchy pattern

Failure Modes

• Mixed tutorial/how-to pages that both teach and direct work
• Reference pages that explain or instruct instead of describing
• Explanation pages that absorb steps, API facts, or setup directions
• Restructuring efforts that begin with empty boxes instead of content improvements
• Using beginner/advanced as the main axis instead of study/work

Load references/distinctions-and-failure-modes.md and references/audit-and-restructure.md when these appear.