diataxis-framework

name	diataxis-framework
description	Diataxis — tutorials, how-to, reference, explanation types.

Diataxis Documentation Framework

Four Document Types

Type	Answers	Oriented to	Example
Tutorial	"Help me learn by doing"	Learning	"Build your first API in 10 minutes"
How-to guide	"Help me accomplish X"	Goals	"How to configure CORS"
Reference	"What is X? What does it do?"	Information	"API endpoint reference"
Explanation	"Why does it work this way?"	Understanding	"How the auth token lifecycle works"

The most common mistake is mixing types in one document. Each document should belong to exactly one type.

Tutorials

• Reader is a learner; guide them step by step
• Every step must work; never skip to an end state
• Use concrete, specific examples (not abstract placeholders)
• Goal: reader succeeds and understands what they just did
• Do not explain why (that is Explanation); just show what to do

How-to Guides

• Reader has a specific goal; they know what they want but not how
• Start from a working system; do not re-explain prerequisites
• Use numbered steps for actions; use bullet lists only for options
• Title format: "How to X" or "X-ing with Y"
• Do not teach concepts (that is Tutorial); just solve the problem

Reference

• Complete, accurate, consistent, non-opinionated
• Describe what it is, not how to use it
• Structure: input → output; parameters; types; constraints; examples
• Should be auto-generated where possible (JSDoc, docstrings, OpenAPI)
• Do not explain decisions (that is Explanation)

Explanation

• Reader wants to understand, not to do
• Discuss trade-offs, history, alternatives, constraints
• Use the word "because" frequently
• Title format: "About X", "Understanding X", "Why X works this way"
• Do not give step-by-step instructions (that is Tutorial/How-to)

Anti-patterns

Anti-pattern	What it mixes	Fix
"Getting started" that also explains internals	Tutorial + Explanation	Separate intro tutorial from architecture doc
README with installation, config reference, and rationale	How-to + Reference + Explanation	Split into three documents
API reference with opinionated usage advice	Reference + How-to	Move advice to a separate how-to guide
Tutorial that skips steps to reach a complex state	Tutorial + Reference	Show every step or link to a simpler prerequisite

Applying Diataxis

When reviewing or authoring docs:

1. Identify what the reader needs (learning, goal, information, or understanding)
2. Choose the corresponding document type
3. Verify the title matches the type (imperative verb → how-to; noun phrase → reference)
4. Check for anti-patterns: if it answers two different questions, split it

When a document is hard to write, it is usually because it is mixing types.