| name | diataxis-classification |
| description | Practical guide for classifying documentation into the four Diataxis quadrants (tutorial, how-to, reference, explanation) — with a decision checklist, anti-pattern catalog, and remediation moves. |
Diataxis Classification
When to Use This
Before writing a new doc or auditing existing content, to ensure you're writing the right kind of thing — serving the reader's actual need rather than mixing quadrants into docs that help nobody well.
The Four Quadrants
| Type | Serves | Reader state | Success criterion |
|---|
| Tutorial | Learning | Newcomer; wants to be led | Reader completes it and has learned something real |
| How-to guide | Accomplishing a task | Practitioner; wants to do X | Reader achieves the specific goal |
| Reference | Information lookup | Expert; wants a fact | Reader finds the fact quickly and trusts its accuracy |
| Explanation | Understanding | Curious; wants to know why | Reader develops a mental model |
The axes are: action vs cognition (doing vs understanding) and acquisition vs application (learning vs working).
Classification Checklist
Ask these questions about your document:
1. Is the reader already using the product, or just starting out?
→ Starting out: Tutorial
→ Already using: How-to, Reference, or Explanation
2. Does the reader want to DO something right now?
→ Yes: Tutorial (guided practice) or How-to (autonomous task)
→ No: Reference (lookup) or Explanation (understanding)
3. Is the reader a newcomer being guided, or a practitioner navigating alone?
→ Guided newcomer: Tutorial
→ Autonomous practitioner: How-to
4. Does the reader want a fact (value, parameter, behavior) or a mental model (why, how it works)?
→ Fact: Reference
→ Mental model: Explanation
Anti-Pattern Catalog
| Anti-pattern | Symptom | Remediation |
|---|
| Tutorial-as-reference | Guided walkthrough ending with a giant parameter table | Split: keep walkthrough as tutorial; extract table to reference |
| How-to buried in tutorial | "Now that you've learned X, here's how to do Y and Z" | Write Y and Z as separate how-to guides; link from tutorial |
| Explanation mixed into reference | API reference with paragraphs about design philosophy | Move philosophy to an explanation doc; reference stays factual |
| Reference used as a tutorial | "See the parameter list to get started" | Write a tutorial that uses the reference; don't merge them |
| Giant catch-all "Overview" page | Contains tutorial steps + design rationale + parameter tables + task instructions | Decompose into one doc per quadrant; overview page links to all four |
Reference vs How-to Decision
The most commonly confused pair:
| Scenario | Correct type |
|---|
| "Here are all the config options and their defaults" | Reference |
| "How to configure authentication with OAuth 2.0" | How-to |
| "Here are all the API endpoints, their parameters, and responses" | Reference |
| "How to authenticate a request" | How-to (uses reference for details) |
| "Here are all the error codes" | Reference |
| "How to handle a 429 rate-limit response" | How-to |
Writing Signals by Type
Tutorial signals — present tense, active voice, guiding tone: "Click Save. You'll see a confirmation…" Minimal explanation, maximum forward momentum.
How-to signals — imperative mood, assumes prior knowledge, no hand-holding: "Configure the webhook endpoint." Reader can skip steps they've done before.
Reference signals — noun-heavy, consistent structure, scannable: function signatures, tables, parameter lists, exact values. No prose narrative.
Explanation signals — discusses trade-offs, uses "because," "in order to," "the reason": "Tokens expire after 15 minutes because long-lived tokens increase the blast radius of a compromise."
Audit Worksheet
For each existing doc, complete:
Doc title: ___________
Intended type (by author): ___________
Actual type (by classification checklist): ___________
Mixed types present: ___________
Remediation: split / rewrite / move / keep
Pitfalls
- Writing tutorials for practitioners — they skip the hand-holding and get lost; they need a how-to.
- Conflating "comprehensive" with "good" — a reference page that explains everything is harder to scan than one that just states facts.
- Writing explanation in the reference page to justify design choices — readers looking up a parameter don't want a philosophy essay; link to the explanation doc.
- Creating an "overview" page to avoid classifying — it becomes the junk drawer that nobody trusts.
See Also
