Chapter 1 · Practice 4 of 4
Pick one type of documentation per page, using Diátaxis
Why it matters
The Diátaxis framework identifies four distinct needs and four forms of documentation, and argues that documentation should be organised around them:
| Type | Orientation | Answers | Form |
|---|---|---|---|
| Tutorial | Learning | "Can you teach me to...?" | A lesson |
| How-to guide | Goals | "How do I...?" | A series of steps |
| Reference | Information | "What is...?" | Dry description |
| Explanation | Understanding | "Why...?" | Discursive explanation |
Most confusing docs mix these: a tutorial interrupted by a full parameter reference, or a how-to guide that wanders into history and design rationale. Decide which one a page is, then move the rest to pages of the right type and link them.
Do
- Label each page as tutorial, how-to, reference or explanation
- Link out instead of mixing types
Avoid
- One giant page that tries to teach, instruct, list and justify at once