The Diátaxis framework is a way to structure and write Documentation by clearly separating it into four distinct types, based on the user’s goal rather than the subject matter:
- Tutorials
- How-to Guides
- Explanation
- Reference
The Diátaxis framework was created by Daniele Procida and is widely used in technical documentation, e.g., see GatsbyJS Documentation. At its core, Diátaxis answers the question: “What is the user trying to do right now?”
Overview
| Property | Tutorials | How-to guides | Reference | Explanation |
|---|---|---|---|---|
| What they do | Introduce, educate, lead | Guide | State, describe, inform | Explain, clarify, discuss |
| Answers the question | “Can you teach me to…?” | “How do I…?” | “What is…?” | “Why…?” |
| Oriented to | Learning | Goals | Information | Understanding |
| Purpose | To provide a learning experience | To help achieve a particular goal | To describe the machinery | To illuminate a topic |
| Form | A lesson | A series of steps | Dry description | Discursive explanation |
| Analogy | Teaching a child how to cook | A recipe in a cookery book | Information on the back of a food packet | An article on culinary social history |