# Páginas de quickstart

## Propósito

Uma página de quickstart é um tutorial cujo objetivo é a primeira ativação de um produto: de não usar o produto até o menor resultado que funciona. Ela segue a forma base do [tutorial](/pt-br/documentacao/guia-de-estilo/conteudo/tutoriais/).

Quickstart é o slot por produto. A seção de onboarding de plataforma em `/documentation/get-started/` tem nome parecido e é outra coisa: ela não pertence a nenhum produto.

## Quando usar

- Escreva uma página de quickstart quando um produto precisa de um caminho documentado até o primeiro resultado que funciona.
- Escreva pelo menos uma página de quickstart por produto, como ponto de entrada logo depois do Overview do produto.
- Adicione um painel de interface quando o primeiro uso de um produto passa por Azion Console, pela Azion CLI ou pela API.
- Não escreva uma página de quickstart para uma tarefa que o leitor já tem em mente. Essa tarefa precisa de um [guia how-to](/pt-br/documentacao/guia-de-estilo/conteudo/guias-how-to/).
- Não compare interfaces nem ofereça opções dentro de um painel. Um painel documenta uma interface, do início ao fim.
- Não escreva uma página de quickstart separada para uma feature. O padrão cobre um produto inteiro.

## Registro

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

## Estrutura

Uma página de quickstart segue o esqueleto do tutorial, com uma diferença: os títulos de etapa não levam número. [Tutoriais](/pt-br/documentacao/guia-de-estilo/conteudo/tutoriais/) argumenta cada parte, e esta lista nomeia o que o padrão exige. Uma página leva o título `<Product> quickstart`, documente ela uma interface ou várias em tabs. Uma página que existe porque as etapas não puderam ser compartilhadas leva `<Product> quickstart using <interface>`: `using Azion Console`, `using the Azion CLI`, `using the API` ou `using an AI agent`.

**Componentes obrigatórios**

- **Abertura**: `Este guia conduz você por <resultado>.` seguido de uma lista curta com marcadores do que o leitor terá feito. Enquadre o resultado como um primeiro: "seu primeiro bucket", "seu primeiro deploy".
- **Cadeia de objetos**: depois da abertura, nomeie cada objeto que o leitor cria e a que cada um precisa ser vinculado, em ordem. Uma lista curta, antes dos pré-requisitos.
- **Pré-requisitos**: uma seção `## Pré-requisitos` com itens em marcadores. Cada item é um link, um comando de uma linha ou uma frase nominal que nomeia o requisito. Um único pré-requisito é uma frase, não uma lista.
- **Etapas**: títulos de etapa sem número, `## <Frase verbal no imperativo>`, na ordem de construção, terminando em uma etapa que ativa ou verifica. `(Opcional)` abre o título de uma etapa opcional: `## (Opcional) Altere o modelo que a função chama`. Cada etapa contém um procedimento e termina com sua frase de resultado. Quando a etapa carrega tabs de interface, o procedimento e a frase de resultado ficam dentro de cada painel.
- **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**

- **Um seletor de interface**: um bloco `<Tabs client:visible sharedStore="interface">` acima dos pré-requisitos, carregando apenas os slots `tab.*`, quando a página documenta mais de uma interface. Cada etapa carrega então um bloco da mesma store com apenas os seus slots `panel.*`.
- **Capturas de tela**: para um passo cujo resultado visível é uma tela, não a saída de um comando.
- **Asides**: raros. Um tutorial cheio de blocos de nota tenta ser material de referência.

## Template

Copie o template e substitua cada `<placeholder>`. Um produto com uma única interface dispensa o bloco `<Tabs>` e escreve o procedimento diretamente sob o título da etapa:

```mdx
import DocCardGroup from '@aziontech/webkit/doc-card-group'
import DocCard from '@aziontech/webkit/doc-card'
import Tabs from '~/components/webkit/Tabs.vue'

Este guia conduz você por <resultado, enquadrado como um primeiro:
seu primeiro bucket, seu primeiro deploy>.

- <O que o leitor terá feito, como uma lista curta>
- <...>

Para <alcançar o resultado>, você cria e conecta estes objetos:

1. <O primeiro objeto, e o que o cria.>
2. <O objeto seguinte, e a que ele precisa ser vinculado.>
3. <O último vínculo, e o que ele torna alcançável.>

---

<Uma frase pedindo que o leitor selecione uma interface, quando a página documenta mais de uma.>

<Tabs client:visible sharedStore="interface">
<Fragment slot="tab.console">Console</Fragment>
<Fragment slot="tab.cli">CLI</Fragment>
<Fragment slot="tab.api">API</Fragment>
</Tabs>

## Pré-requisitos

- <O que toda interface precisa.>

<Tabs client:visible sharedStore="interface">

<Fragment slot="panel.console">

- <O que só esta interface precisa.>

</Fragment>

</Tabs>

## <Frase verbal no imperativo>

<O que esta etapa produz, em termos que toda interface compartilha.>

<Tabs client:visible sharedStore="interface">

<Fragment slot="panel.console">

Para <alcançar o resultado da etapa> no Azion Console:

1. <Um procedimento, numerado quando tem duas ou mais ações.>

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

</Fragment>

<Fragment slot="panel.cli">

<...>

</Fragment>

<Fragment slot="panel.api">

<...>

</Fragment>

</Tabs>

## <Frase verbal no imperativo>

<...>

## <Frase verbal no imperativo que ativa 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

- **Declare a cadeia de objetos antes do primeiro passo.** Nomeie cada objeto que o leitor cria e a que ele precisa ser vinculado, em ordem. Um quickstart que lista cliques sem o modelo de composição deixa o leitor incapaz de repetir o resultado com outros objetos.
- **O leitor seleciona a interface uma vez, no início da página.** Um bloco `<Tabs>` acima dos pré-requisitos carrega os slots `tab.*` e nada mais: essa é a única faixa de tabs da página. Cada etapa carrega o próprio bloco da mesma store, com apenas os slots `panel.*`, e não renderiza faixa alguma. O título da etapa e a frase que a apresenta ficam fora do bloco, então a página mantém uma entrada por etapa no sumário. Console primeiro. A mecânica está em [Componentes](/pt-br/documentacao/guia-de-estilo/componentes/).
- **Divida também os pré-requisitos.** O que toda interface precisa fica na lista. O que só uma interface precisa vai em um bloco de painéis logo abaixo, para que o leitor nunca leia um requisito que não é dele. Quando o painel passa a carregar o item, remova o qualificador que nomeava a interface.
- **A tab seleciona a interface, não o caminho.** Cada painel cria os mesmos objetos, nas mesmas etapas, até o mesmo resultado verificado, e só a mecânica muda. É por isso que um quickstart usa tabs onde um [tutorial](/pt-br/documentacao/guia-de-estilo/conteudo/tutoriais/) não usa: o leitor continua sem escolher nada sobre o que constrói.
- **Dê a todos os blocos o mesmo `sharedStore="interface"` e as mesmas chaves de painel.** A seleção única então governa todas as etapas, e acompanha o leitor até a página seguinte. Uma etapa que omite uma interface que o seletor oferece abre no próprio primeiro painel, o que move o leitor para outra interface no meio da página, sem avisar.
- **Escreva cada painel para ser lido sozinho.** A frase de entrada nomeia a interface, e a frase de resultado fica dentro do painel: o Azion Console mostra uma lista onde a API retorna um corpo de resposta. Nunca escreva "como você selecionou acima": a seleção acompanha o leitor até a página seguinte, mas uma página que não oferece aquela interface abre no próprio primeiro painel.
- **Divida em páginas separadas quando as etapas não podem ser compartilhadas.** Interfaces que precisam de etapas diferentes, ou de outra cadeia de objetos, são caminhos diferentes, não mecânicas diferentes. Dê a cada uma sua própria página, com o título `<Product> quickstart using <interface>`, sob um único grupo Quickstart na barra lateral, com o Console primeiro. O grupo é um pai de menu, não uma página. Nomeie os irmãos em uma linha logo abaixo da abertura: `Prefere a CLI? Consulte [<Product> quickstart using the Azion CLI](/caminho/).`
- **Um primeiro uso por agente de IA é sempre sua própria página.** Um caminho que o leitor conduz por prompt não compartilha etapa com um caminho de cliques nem com um comando. Dê a ela o título `<Product> quickstart using an AI agent`, conectada pelo [servidor MCP da Azion](/pt-br/documentacao/agent-setup/), e nomeie-a na linha dos irmãos.
- **Documente apenas a interface que você rodou do início ao fim.** Deixe de fora o painel que você ainda não consegue verificar, em vez de preencher os passos dele a partir dos outros painéis. Um caminho de primeiro uso desatualizado falha com o leitor no primeiro contato.
- **Escreva cada etapa como um procedimento.** Os passos seguem [Procedimentos](/pt-br/documentacao/guia-de-estilo/escrita/procedimentos/), e cada etapa termina com sua frase de resultado.
- **Refira-se a uma etapa pelo que ela produz, nunca pelo número.** Os títulos não levam número, então "o ID da etapa 1" não aponta para nada. Nomeie o objeto: "o `id` da zona que você criou", "`curl`, para enviar a requisição final".
- **Mantenha os pré-requisitos no mínimo real.** Cada item é um motivo para abandonar a página.
- **Termine em uma etapa que ativa ou verifica.** O leitor sai com a prova do resultado que funciona.
- **Aponte tutoriais e os principais how-tos em `## Próximos passos`.** Dê a cada card seu motivo.
- **Teste todo comando antes de publicar.** Uma instrução por passo, e um resultado visível em cada um.
- **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/).
- **Coloque a página logo depois do Overview do produto.**

## Exemplos

Este exemplo, em inglês, mostra a abertura, a cadeia de objetos e os pré-requisitos de uma página de quickstart de **Functions**:

```mdx
This guide instructs you through running your first function on the Azion Web Platform.

- Create a function and write its code.
- Connect the function to an application and a workload.
- Verify that the function answers a request.

To run a function, you create and connect these objects:

1. A **function**, which holds the code.
2. A **function instance**, which binds the function to an application.
3. A **rule** in the Rules Engine, which decides the requests that trigger the instance.
4. A **workload**, which the application is linked to and which receives the traffic.

---

## Prerequisites

- An [Azion account](https://console.azion.com/).
```

A cadeia explica ao leitor por que quatro objetos existem antes de uma requisição chegar ao código dele. Sem ela, os passos parecem cliques sem explicação.

Este exemplo, em inglês, mostra o seletor no início da mesma página e, depois, uma etapa. A faixa é declarada uma vez; o bloco da etapa carrega apenas painéis. O título da etapa e a frase que a enquadra ficam fora do bloco, e cada painel carrega sua própria frase de entrada e sua própria frase de resultado:

```mdx
Select the interface you will use. Every stage below follows that choice.

<Tabs client:visible sharedStore="interface">
<Fragment slot="tab.console">Console</Fragment>
<Fragment slot="tab.cli">CLI</Fragment>
</Tabs>

## Create the function

A function holds the code. It runs only once an instance binds it to an application.

<Tabs client:visible sharedStore="interface">

<Fragment slot="panel.console">

To create the function in Azion Console:

1. Access [Azion Console](https://console.azion.com/) > **Functions**.
2. Select **+ Function**.
3. Enter a **Name** for the function.
4. Select **Save**.

The function appears in **Functions**, which lists its **Last Editor** and **Last Modified**.

</Fragment>

<Fragment slot="panel.cli">

To create the function with the Azion CLI:

<Code client:visible lang="bash" code={`azion create function --name my-function --code ./index.js`} />

The command returns the function's ID, which the next stage binds to an application.

</Fragment>

</Tabs>
```

Os dois painéis alcançam o mesmo objeto, então o título da etapa e a cadeia de objetos valem para qualquer leitor.

## Relacionados

- [Tutoriais](/pt-br/documentacao/guia-de-estilo/conteudo/tutoriais.md): A forma base que este padrão aplica.
- [Guias how-to](/pt-br/documentacao/guia-de-estilo/conteudo/guias-how-to.md): Para onde vão as opções e as alternativas.
- [Arquitetura de informação](/pt-br/documentacao/guia-de-estilo/conteudo/arquitetura-de-informacao.md): Onde a página fica na seção de produto.
- [Escolher um tipo de conteúdo](/pt-br/documentacao/guia-de-estilo/conteudo/escolher-um-tipo-de-conteudo.md): O catálogo completo de tipos de página.