How to use this documentation

The pages in this documentation fall into four types, each written to serve a different kind of need. A coloured badge beside every page’s title names its type, so you can see at a glance what kind of help the page offers. The left-hand navigation groups pages by product area and task. Within a group, pages follow the type order: tutorials first, straight after the group’s introduction, then explanations, how-to guides, and reference pages. Where a group covers several topics, each topic’s pages stay together, in that same order. The types differ along two lines: whether a page is practical, tied to doing something, or theoretical, about knowledge; and whether it serves you while you are learning a subject or while you are working in it.

Tutorial

A tutorial is a lesson that teaches through doing. It leads you through a subject step by step so you gain a first footing in something unfamiliar. The material sets the path, not your own goals, and understanding follows from the doing.

Explanation

An explanation steps back from the immediate task to discuss how and why something works. It covers background, reasoning, and how the parts fit together, and suits readers who want to understand a subject rather than act on it.

How-to guide

A how-to guide gives the steps that get a particular job done. It assumes you already know what you want to achieve, and does not pause to teach the concepts behind the task.

Reference

Reference material states the facts about the product, such as settings, fields, values, and behaviour, plainly and without commentary. You consult it to check a detail while working, rather than reading it end to end.

These two lines place the four types in a simple grid:

Practical (doing) Theoretical (knowing)

While learning

Tutorial

Explanation

While working

How-to guide

Reference

This scheme comes from the Diátaxis framework.