Diátaxis Quickstart

A summary of each document type and purpose.

1. Tutorial:

1. Allow the learner to understand what goals they will achieve before they start.

2. A tutorial helps a beginner achieve basic competence.

3. Allow the user to learn by doing.

4. Get the learner productive and succeeding from the very start.

2. How-to:

1. How-to guides are goal-oriented directions, much like a recipe.

2. The goal of a how-to is to solve a problem or complete an unfamiliar task.

3. Explanations aren’t necessary when following a how-to guide.

4. How-to guides should be flexible and adaptable to many use cases.

3. Reference:

1. References are technical descriptions of the machinery and how to operate it.

2. A reference guides focus is the product and must describe it as succinctly as possible.

3. Users consult reference material, so it should not contain any ambiguity.

4. Discussions:

1. Discussions clarify and illuminate a particular topic.

2. Discussions are understanding-oriented.

3. Discussions deepen and broaden the reader’s understanding of a subject.

4. Connections, even to things outside the immediate topic, can add clarity and context.

Further Reading

Diátaxis Introduction

Diátaxis Tutorials

Diátaxis How-To

Diátaxis Reference

Diátaxis Discussions