# 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](https://diataxis.fr/start-here/).

To understand why we use Diátaxis, see [ADR-013 (Wiki structure)](../explanations/adrs/adr-013-wiki-structure.md).