Introduction to Diátaxis
Diátaxis is a framework that categorizes documentation in four subgroups, each of which requires a different approach and serves a different purpose. Additionally, these groups are placed on a map determining whether they are action- or cognition-based, and acquisition- or application-based. These are the subgroups:
1. Tutorials
Tutorials are lessons that try to make the user learn something by executing tasks given by an instructor. Tutorials must be written in such a way that the instructor can guide the user to success solely through the provided instructions.
On the Diátaxis map, tutorials are classified as action- and acquisition-based.
2. How-to guides
Similar to tutorials, how-to guides provide detailed instructions on how to reach a specific goal. Unlike tutorials, however, they do not intend to impart new knowledge, but to use existing knowledge to complete a task. These tasks therefore often involve reaccuring procedures or resolving common problems.
On the Diátaxis map, how-to guides are classified as action- and application-based.
3. References
References are written in a less specific style, but, like how-to guides, they still serve to help the user carry out practical tasks. They do not contain any detailed instructions.
On the Diátaxis map, references are classified as cognition- and application-based.
4. Explanations
Explanations are also theoretical in nature, but unlike how-to guides, they are less concerned with helping the user execute tasks. Instead, they aim to answer background questions and address the user’s knowledge, not work.
On the Diátaxis map, explanations are classified as cognition- and acquisition-based.
For more information, see here.
To understand why we use Diátaxis, see ADR-013 (Wiki structure).