# 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](/en/documentation/style-guide/content/reference/).

**Write something else when:**

- The reader arrived with the task already in mind. That is a [how-to guide](/en/documentation/style-guide/content/how-to-guides/).
- The page activates a product for the first time. That is a [quickstart](/en/documentation/style-guide/content/quickstart/).
- The page builds a Use Case from the catalog end to end. That is a [use case](/en/documentation/style-guide/content/use-cases/).
- The subject is fields, values, and defaults. That is [reference](/en/documentation/style-guide/content/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](/en/documentation/style-guide/content/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](/en/documentation/style-guide/writing/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](/en/documentation/style-guide/content/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>`:

```mdx
import DocCardGroup from '@aziontech/webkit/doc-card-group'
import DocCard from '@aziontech/webkit/doc-card'

In this tutorial, you will <verb> <the artifact and its goal>.
You will create <...>, configure <...>, and deploy <...>.

## Prerequisites

- <A link or a one-line command where one exists, otherwise a noun phrase>

## 1. <Imperative verb phrase>

<A procedure. Every step shows a visible result.>

<The outcome sentence: what the reader now has or sees.>

## 2. <Imperative verb phrase>

<...>

## 3. (Optional) <Imperative verb phrase>

<An optional stage. `(Optional)` follows the number.>

## 4. <Imperative verb phrase that deploys or verifies>

<...>

## Next steps

<DocCardGroup cols={2}>
  <DocCard title="Title" href="/path/" label="one sentence on why the reader would follow it." />
  <DocCard title="Title" href="/path/" label="one sentence on why the reader would follow it." />
</DocCardGroup>
```

## 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](/en/documentation/style-guide/content/how-to-guides/). The one exception is a [Quickstart page](/en/documentation/style-guide/content/quickstart/), 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](/en/documentation/style-guide/writing/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:

```mdx
In this tutorial, you will build a user list API with **Functions** and **SQL Database**. You will create a database, seed a `users` table, create a function, and route requests to it.

## Prerequisites

- An Azion account with a configured personal token
- An application with a domain in the format `<id>.map.azionedge.net`

---

## 1. Create the database

To create the database, send a `POST` request to the databases endpoint:

<Code client:visible lang="bash" code={`curl --location 'https://api.azion.com/v4/workspace/sql/databases' \\
--header 'Authorization: Token [TOKEN VALUE]' \\
--header 'Content-Type: application/json' \\
--data '{"name": "mydatabase"}'`} />

The response returns `"state": "pending"` and `"status": "creating"`. Database creation is asynchronous.

To check the creation status, send `GET` requests to the same endpoint until `status` is `created`:

<Code client:visible lang="bash" code={`curl --location 'https://api.azion.com/v4/workspace/sql/databases' \\
--header 'Authorization: Token [TOKEN VALUE]'`} />

The database is ready when `status` is `created`.
```

## Related

- [Quickstart pages](/en/documentation/style-guide/content/quickstart.md): The tutorial whose goal is first activation.
- [How-to guides](/en/documentation/style-guide/content/how-to-guides.md): The page for the reader who arrived with a task.
- [Choose a content type](/en/documentation/style-guide/content/choose-a-content-type.md): The router.