Tutorials

Purpose

A tutorial teaches the product by having the reader build something that works. The author chooses the goal, guarantees the result, and keeps every decision away from the reader.

When to use

Recognize a tutorial by:

• A reader who has chosen the product and has not yet built anything with it.
• One artifact that works when the last stage ends.
• A single path the author chose and guarantees, from the first command to a verified result.
• Learning that arrives as a side effect of building, never as a lecture.

It is still a tutorial when:

• It uses more than one product, because the artifact needs them. The author chose the goal, and that is what decides the kind.
• It builds against a third-party service that belongs to the artifact. Name the vendor’s step and link out; never document their interface.
• It runs entirely in Azion Console, because that is the honest path to the result.
• It leaves out a capability the artifact does not need. Completeness belongs to reference.

Write something else when:

• The reader arrived with the task already in mind. That is a how-to guide.
• The page activates a product for the first time. That is a quickstart.
• The page builds a Use Case from the catalog end to end. That is a use case.
• The subject is fields, values, and defaults. That is reference.
• Nothing is finished at the end. Steps that end nowhere teach nothing, so find the artifact or drop the page.

When two kinds still look possible, Choose a content type has the router.

Register

Procedural: 20 words per sentence, one instruction per step, imperative and active. Tone: directive, plain, instructive, certain. Sentence structure holds the rules.

Structure

The title is an imperative verb phrase naming the artifact: Build a comments API, Deploy a static site with Functions.

Required components

• Opening move: In this tutorial, you will <verb> <the artifact and its goal>. Then one sentence enumerating the sub-goals: “You will create …, configure …, and deploy …“.
• Prerequisites: a ## Prerequisites section, always first, each item a link or a one-line command where one exists, otherwise a noun phrase.
• Stages: numbered stage headings, ## 1. <Imperative verb phrase>, in build order. (Optional) may follow the number: ## 8. (Optional) Add a custom domain. The final stage deploys or verifies.
• Next steps: a ## Next steps closing, a DocCardGroup with one card per destination: the title, the link, and one sentence on why the reader would follow it.

Optional components

• One concept sentence with a link to a concept page, when a concept is genuinely required.
• An image as the visible result of a step, when words alone cannot show it.

Template

Copy the template and replace each <placeholder>:

Rules

• Keep the contract. You choose every option: no branching, no “depending on your needs”. Every step shows a visible result, and you have run every command.
• No <Tabs>. Tabs are a branch, and tutorials do not branch. A task that genuinely needs three interfaces is a how-to guide. The one exception is a Quickstart page, where a tab selects the reader’s interface and not the path: every panel builds the same objects, in the same stages, to the same outcome.
• Do not explain. One sentence and a link when a concept is genuinely required. Keep asides rare.
• Make every screenshot earn its place. One image for a result words cannot show, never a shot of every screen the reader passes.
• Link out for third-party products. Name the vendor’s step; do not document their interface.
• Give every code block a colon lead-in. “Install the CLI:” then the command. Use <Code> for anything the reader copies.
• Show the output after every command. The reader sees what success looks like before the next step depends on it. The rule is in Procedures.
• Keep tutorials scarce. One per product area. Tutorials are expensive to keep working.
• Link the how-tos and concepts the tutorial touched in ## Next steps. Give each card its reason.

Examples

This excerpt builds a user list API. It shows the opening move, the prerequisites, and the first stage:

Related