Documentation FundamentalsLesson 1.2
The four types of documentation every project needs
Diátaxis framework, tutorials, how-to guides, reference docs, explanations, documentation taxonomy, content classification
The Four Types of Documentation
Every piece of documentation falls into one of four categories, defined by the Diátaxis framework. Mixing them is the most common structural mistake in developer docs.
The Four Types
- Tutorials — Learning-oriented. Takes a beginner through a complete task step by step. Success = the reader finishes something that works. Example: "Build your first REST API in 15 minutes."
- How-To Guides — Task-oriented. Assumes competence, solves a specific problem. Example: "How to configure OAuth 2.0 authentication."
- Reference — Information-oriented. Dry, accurate, complete. API docs are reference. No storytelling, just facts.
- Explanation — Understanding-oriented. Answers "why" not "how." Example: "Why we use event sourcing instead of CRUD."
Why Mixing Types Breaks Docs
When a tutorial suddenly becomes a reference page mid-flow, learners get lost. When a how-to becomes an explanation, readers lose the thread. Each document should serve exactly one purpose.
Quick Classification Test
Before writing any doc, answer: Is the reader learning, doing, looking something up, or trying to understand? That answer tells you which type to write — and what to exclude.