Skip to main content
Unlisted page
This page is unlisted. Search engines will not index it, and only users having a direct link can access it.
Last updated on

Tutorial

↑ Docs content model

A tutorial is a guided, end-to-end walkthrough that takes a reader from a defined starting point to a concrete working result. It is a learning experience, not a reference: the reader follows every step in order and ends with something that works.

When to use​

Use a tutorial when:

  • A reader needs to accomplish a complete, realistic outcome for the first time.
  • The path has a clear beginning and end and can be followed in one sitting.

Use a how-to instead when the reader already knows the concepts and just needs the steps for one task, and a concept when the goal is understanding rather than doing.

Composed of​

A tutorial is assembled from these page sections, in order:

  1. Overview — what the reader will build and learn.
  2. Prerequisites — what they need before starting.
  3. Procedure — the ordered steps (often the bulk of the page).
  4. Next steps — where to go after finishing.

Technical details​

  • Frontmatter. Include a title and a description; the description is the summary shown in search and previews. See the frontmatter atom.
  • Headings. One H1 (the title). Prerequisites and each major phase of the procedure are H2s. Keep the heading depth shallow — no deeper than H3.
  • Steps. Write the procedure as an ordered list, or use the :::div[steps] atom for a visually distinct sequence.
  • One page. A tutorial is a single page. If it grows past one sitting, it is probably a how-to series instead.

Rules​

  • The tutorial must be completable using only what its prerequisites section lists.
  • Every step must produce an observable result the reader can check before moving on.
  • Do not branch. A tutorial follows one path; move optional variations to a how-to.

Style​

  • Use the imperative mood for steps ("Click Create", not "You can click Create").
  • Address the reader as "you". Keep sentences short and each step to a single action.
  • Show expected output or UI state so the reader knows they are on track.

Template​

Markdown
---
title: <What the reader will accomplish>
description: <One-sentence summary for search and previews.>
---

# <Tutorial title>

<Overview: what you'll build and learn.>

## Before you begin

<Prerequisites.>

## <First phase of the procedure>

1. <Step.>
1. <Step.>

## <Next phase>

1. <Step.>

## Next steps

- <Where to go next.>

Examples​

A "Get started" tutorial for a new product opens with a one-paragraph overview, lists its prerequisites, walks through creating and running the first object in a numbered procedure, and ends with next-steps links into the how-to pages.

Used in​

  • New product — a new product doc set includes a tutorial as its first working result.
On this page