Skip to main content

Tutorial Pages

Overview​

Use a tutorial when the reader needs guided learning and you are responsible for keeping them on a safe, linear path.

Tutorials are not reference pages and they are not concept essays. They should teach by building or configuring something real from start to finish.

The primary reader question is: "Can you walk me through one complete path so I learn by doing instead of assembling the pieces myself?"

Use This Page Type When​

  • the reader is learning by doing
  • the page should provide one complete end-to-end path
  • the reader should not need to infer hidden code or missing setup

Required Structure​

  1. one-sentence statement of what the reader will build
  2. ## Before you begin
  3. ## Step 1, ## Step 2, and so on in strict sequence
  4. verification checkpoints after major steps
  5. ## Summary
  6. ## Next Steps

Content Rules​

  • Use one linear path from start to finish.
  • Introduce concepts only when the next step needs them.
  • Use complete, verified code.
  • Prefer one real project over many fragments.
  • Move deeper explanation to concept pages and link out.

Minimal Frontmatter Example​

---
title: Build a Money Transfer Saga
description: Learn Mississippi saga orchestration by building a verified end-to-end money transfer workflow.
sidebar_position: 20
sidebar_label: Money Transfer Saga
---

Page Skeleton Example​

# Build a Money Transfer Saga

Build a saga that coordinates a transfer workflow and verify each major step as you go.

## Before you begin

## Step 1

## Checkpoint

## Step 2

## Checkpoint

## Summary

Tutorials teach one complete path from start to finish.

They should keep the reader moving forward with explicit steps, verification checkpoints, and only the theory needed for the next action.

## Next Steps