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.

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.
• 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 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 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:

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.
• 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 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, 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, 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.
• 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:

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:

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