Splitting documentation into multiple categories can make the documentation much clearer.
Table of contents
4 types
Divio's documentation system splits documentation into four types:
- Tutorials are learning-oriented; they teach how to get started.
- How-to guides are problem-oriented; they guide how to achieve a certain goal.
- Explanations are understanding-oriented; they clarify a certain topic.
- References are information-oriented; they describe the system and how to use it. (E.g. what methods are available, what parameters they take and what they return.)
The four types are quite similar to each other.
But if you don't realize that there are these different types of documentation, the types get mixed very easily, and the documentation gets messy.
Alternative descriptions
From a Reddit comment by Kinrany:
- Tutorial: practical steps for learning.
- How-to guide: practical steps for working.
- Explanation: theoretical knowledge for learning.
- Reference: theoretical knowledge for working.
Different names
A good point from a related discussion on Hacker News: the different types may have different names.
For example, explanations could also be called:
- Backgrounds
- Deep dives
- Discussions
- Overviews
- Rationales.
More types
Another good point from the Hacker News discussion: there can be other types of documentation as well.
For example:
- Introduction
- Announcements
- Case studies
- Code samples
- Release notes.
These types might fit into one of the four categories, or they might not.