diataxis-docs

Diátaxis documentation

Use Diátaxis as a decision tool, not a four-folder template. Start from the reader's immediate need, give each page one primary purpose, and link across purposes when the reader is likely to need a different kind of help.

Read references/framework.md before a broad documentation audit, information-architecture change, or ambiguous classification. It records the primary sources, the compass, and the distinctions most often lost in shorter skills.

Classify the need

Ask two questions internally:

1. Does the reader need action or understanding?
2. Are they acquiring skill or applying existing skill?

Map the answers:

Reader need	Mode	Documentation type
Learn by doing	action + acquisition	Tutorial
Complete a real task	action + application	How-to guide
Look up facts while working	cognition + application	Reference
Understand reasons and relationships	cognition + acquisition	Explanation

Infer the type when the evidence is clear. Ask only when choosing incorrectly would materially change the requested artifact.

Choose the operation

Create or revise one page

1. State the intended reader and outcome in working notes.
2. Select one primary documentation type.
3. Preserve accurate repository-specific facts and examples.
4. Write according to the type rules below.
5. Move substantial off-purpose material to a better page, or link to an existing page.
6. Check navigation so the reader has an obvious next destination.

Audit a documentation set

1. Inventory pages and their apparent audience.
2. Classify each page by its dominant need; record uncertain or mixed pages.
3. Find user journeys and missing destinations, not merely empty quadrants.
4. Flag misleading titles, duplicated material, stale facts, dead ends, and mixed-purpose pages.
5. Recommend the smallest useful restructure. Do not create empty sections merely to complete a matrix.
6. Report evidence and concrete moves, splits, merges, or links.

Restructure mixed documentation

1. Preserve the source material and map every substantive section.
2. Choose a primary page for each distinct reader need.
3. Split only where the mix harms usability; short context or a small example may remain.
4. Replace duplication with purposeful cross-links.
5. Keep landing pages and READMEs as routing surfaces. They may summarize several types without pretending to be one of them.
6. Verify that no claims or operational steps were lost.

Write by type

Tutorial

• Own the learner's success.
• Provide one reliable path with an early visible result.
• Use concrete steps, expected observations, and a coherent learning sequence.
• Minimize branching, alternatives, and extended theory.
• Test commands and examples when the repository permits it.

How-to guide

• Start from a specific real-world goal.
• Assume a competent practitioner and omit foundational teaching.
• Use ordered actions and conditionals only where the task requires them.
• Include prerequisites and success checks.
• Link to reference facts instead of reproducing exhaustive option lists.

Reference

• Describe the machinery accurately, completely, and consistently.
• Mirror the product or API structure.
• Prefer stable headings, tables, signatures, defaults, constraints, and edge cases.
• Keep instruction and rationale subordinate; link outward for tasks and concepts.
• Generate from authoritative interfaces where possible, then verify the result.

Explanation

• Explain why the subject exists and how its parts relate.
• Discuss constraints, history, alternatives, and tradeoffs.
• Connect the topic to adjacent concepts.
• Avoid turning the page into a numbered procedure or an exhaustive field catalog.

Respect repository context

• Follow existing terminology, style, navigation, and contribution rules.
• Treat plans, decision records, research notes, release notes, and issue backlogs as valid genres outside the four product-documentation types.
• Keep a README focused on orientation, first success, status, and routes to deeper documentation.
• Preserve existing document frontmatter; Diátaxis classification does not authorize removing or rewriting repository metadata conventions.
• Treat index.md files as navigation surfaces. Do not flag their purposeful links and short descriptions as duplicated human-facing documentation.
• Prefer gradual improvement over a repository-wide rewrite without evidence.
• Do not sacrifice accuracy, runnable examples, accessibility, or source attribution for quadrant purity.

Final check

• Identify the primary reader need in one sentence.
• Confirm the title signals that need.
• Confirm the page behaves like its chosen type.
• Split or link only where another need would interrupt the page's flow.
• Verify facts and examples against current sources.
• Make the next step discoverable.
• Confirm existing frontmatter remains intact and navigation indexes were not mistaken for duplicate content.