# Tutoriais

## Propósito

Um tutorial ensina o produto ao levar o leitor a construir algo que funciona. O autor escolhe o objetivo, garante o resultado e mantém todas as decisões longe do leitor.

## Quando usar

**Reconheça um tutorial por:**

- Um leitor que já escolheu o produto e ainda não construiu nada com ele.
- Um artefato que funciona quando a última etapa termina.
- Um caminho único que o autor escolheu e garante, do primeiro comando até um resultado verificado.
- Aprendizado que chega como efeito de construir, nunca como aula.

**Continua sendo um tutorial quando:**

- Usa mais de um produto, porque o artefato precisa deles. O autor escolheu o objetivo, e é isso que decide o tipo.
- Constrói sobre um serviço de terceiro que faz parte do artefato. Nomeie o passo do fornecedor e aponte para fora; nunca documente a interface dele.
- Roda inteiramente no Azion Console, porque esse é o caminho honesto até o resultado.
- Deixa de fora uma capacidade que o artefato não precisa. Completude é assunto de [referência](/pt-br/documentacao/guia-de-estilo/conteudo/referencia/).

**Escreva outra coisa quando:**

- O leitor chegou com a tarefa já em mente. Isso é um [guia how-to](/pt-br/documentacao/guia-de-estilo/conteudo/guias-how-to/).
- A página ativa um produto pela primeira vez. Isso é um [quickstart](/pt-br/documentacao/guia-de-estilo/conteudo/quickstart/).
- A página constrói um caso de uso do catálogo do início ao fim. Isso é um [caso de uso](/pt-br/documentacao/guia-de-estilo/conteudo/casos-de-uso/).
- O assunto é campos, valores e padrões. Isso é [referência](/pt-br/documentacao/guia-de-estilo/conteudo/referencia/).
- Nada fica pronto no fim. Passos que não terminam em nada não ensinam nada, então encontre o artefato ou descarte a página.

Quando dois tipos ainda parecem possíveis, [Escolher um tipo de conteúdo](/pt-br/documentacao/guia-de-estilo/conteudo/escolher-um-tipo-de-conteudo/) tem o roteiro.

## Registro

Procedural: 20 palavras por frase, uma instrução por passo, imperativo e ativo. Tom: diretivo, claro, didático, seguro. [Estrutura de frases](/pt-br/documentacao/guia-de-estilo/escrita/estrutura-de-frases/) tem as regras.

## Estrutura

O título é uma frase verbal no imperativo que nomeia o artefato: `Construa uma API de comentários`, `Faça o deploy de um site estático com Functions`.

**Componentes obrigatórios**

- **Abertura**: `Neste tutorial, você vai <verbo> <o artefato e seu objetivo>.` Depois, uma frase que enumera os subobjetivos: "Você vai criar ..., configurar ... e fazer o deploy de ...".
- **Pré-requisitos**: uma seção `## Pré-requisitos`, sempre primeiro, cada item um link ou um comando de uma linha quando existe um, senão uma frase nominal.
- **Etapas**: títulos de etapa numerados, `## 1. <Frase verbal no imperativo>`, na ordem de construção. `(Opcional)` pode vir depois do número: `## 8. (Opcional) Adicione um domínio personalizado`. A etapa final faz o deploy ou verifica.
- **Próximos passos**: um fechamento `## Próximos passos`, um `DocCardGroup` com um card por destino: o título, o link e uma frase sobre por que o leitor seguiria o link.

**Componentes opcionais**

- **Uma frase de conceito** com link para uma página de [conceito](/pt-br/documentacao/guia-de-estilo/conteudo/conceito/), quando um conceito é genuinamente necessário.
- **Uma imagem** como resultado visível de um passo, quando as palavras sozinhas não mostram.

## Template

Copie o template e substitua cada `<placeholder>`:

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

Neste tutorial, você vai <verbo> <o artefato e seu objetivo>.
Você vai criar <...>, configurar <...> e fazer o deploy de <...>.

## Pré-requisitos

- <Um link ou um comando de uma linha quando existe um, senão uma frase nominal>

## 1. <Frase verbal no imperativo>

<Um procedimento. Cada passo mostra um resultado visível.>

<A frase de resultado: o que o leitor agora tem ou vê.>

## 2. <Frase verbal no imperativo>

<...>

## 3. (Opcional) <Frase verbal no imperativo>

<Uma etapa opcional. `(Opcional)` vem depois do número.>

## 4. <Frase verbal no imperativo que faz o deploy ou verifica>

<...>

## Próximos passos

<DocCardGroup cols={2}>
  <DocCard title="Título" href="/caminho/" label="uma frase sobre por que o leitor seguiria o link." />
  <DocCard title="Título" href="/caminho/" label="uma frase sobre por que o leitor seguiria o link." />
</DocCardGroup>
```

## Regras

- **Cumpra o contrato.** Você escolhe cada opção: sem ramificação, sem "dependendo das suas necessidades". Cada passo mostra um resultado visível, e você rodou todo comando.
- **Sem `<Tabs>`.** Tabs são uma ramificação, e tutoriais não ramificam. Uma tarefa que genuinamente precisa de três interfaces é um [guia how-to](/pt-br/documentacao/guia-de-estilo/conteudo/guias-how-to/). A única exceção é uma [página de quickstart](/pt-br/documentacao/guia-de-estilo/conteudo/quickstart/), onde a tab seleciona a interface do leitor e não o caminho: cada painel constrói os mesmos objetos, nas mesmas etapas, até o mesmo resultado.
- **Não explique.** Uma frase e um link quando o conceito é genuinamente necessário. Mantenha os asides raros.
- **Toda captura de tela precisa se justificar.** Uma imagem para um resultado que as palavras não mostram, nunca um print de cada tela pela qual o leitor passa.
- **Aponte para fora nos produtos de terceiros.** Nomeie o passo do fornecedor; não documente a interface dele.
- **Dê a cada bloco de código uma introdução com dois-pontos.** "Instale a CLI:" e depois o comando. Use `<Code>` para tudo que o leitor copia.
- **Mostre o output depois de cada comando.** O leitor vê como o sucesso se parece antes que o próximo passo dependa dele. A regra está em [Procedimentos](/pt-br/documentacao/guia-de-estilo/escrita/procedimentos/).
- **Mantenha tutoriais escassos.** Um por área de produto. Tutoriais são caros de manter funcionando.
- **Aponte os how-tos e conceitos que o tutorial tocou em `## Próximos passos`.** Dê a cada card seu motivo.

## Exemplos

Este exemplo, em inglês, mostra a abertura, os pré-requisitos e a primeira etapa de um tutorial que constrói uma API de lista de usuários:

```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`.
```

## Relacionados

- [Páginas de quickstart](/pt-br/documentacao/guia-de-estilo/conteudo/quickstart.md): O tutorial cujo objetivo é a primeira ativação.
- [Guias how-to](/pt-br/documentacao/guia-de-estilo/conteudo/guias-how-to.md): A página para o leitor que chegou com uma tarefa.
- [Escolher um tipo de conteúdo](/pt-br/documentacao/guia-de-estilo/conteudo/escolher-um-tipo-de-conteudo.md): O roteiro.