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.

Escreva outra coisa quando:

• O leitor chegou com a tarefa já em mente. Isso é um guia how-to.
• A página ativa um produto pela primeira vez. Isso é um quickstart.
• A página constrói um caso de uso do catálogo do início ao fim. Isso é um caso de uso.
• O assunto é campos, valores e padrões. Isso é referência.
• 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 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 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, 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>:

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. A única exceção é uma página de 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.
• 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:

Relacionados