Tutorials
Write a tutorial: the author picks the goal, guarantees the result, and keeps every decision away from the reader.
Purpose
A tutorial teaches a Platform Resource 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 Platform Resource 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 Platform Resource, 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 Platform Resource for the first time. That is a quickstart.
- The page explains a Use Case from the catalog. 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
## Prerequisitessection, 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 stepsclosing, aDocCardGroupwith 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 services. 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 Platform Resource 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: