Guias how-to

Propósito

Um guia how-to leva um leitor com um problema até o problema resolvido. O leitor já sabe o que quer. A página remove os obstáculos entre ele e o resultado; ela não ensina.

Quando usar

• O leitor chegou com uma tarefa específica e uma situação real.
• Não use um how-to para o leitor que está aprendendo o produto: essa página é um tutorial.
• Um how-to cuja tarefa é um conserto é uma página de troubleshooting.
• Na dúvida, 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, eficiente. Estrutura de frases tem as regras.

Estrutura

Componentes obrigatórios

• Frase de escopo: a abertura declara, em uma frase, o que a página permite ao leitor fazer e a partir de onde. Nunca Neste guia.
• Pré-requisitos: uma seção ## Pré-requisitos quando a página tem algum, em lista; cada item é um link ou um comando de uma linha. Um único pré-requisito é uma frase, não uma lista.
• Seções de tarefa: um ## por tarefa, cada um uma frase verbal no imperativo.
• Lead-in: logo antes de cada procedimento, uma frase terminada em dois-pontos, como Para criar o bucket:.
• Frase de resultado: todo procedimento termina declarando o que o leitor agora tem ou vê.
• Próximos passos: uma seção final ## Próximos passos, um DocCardGroup com um ou dois cards: o título, o link e o motivo como texto do card.

Componentes opcionais

• Tabs por interface: um bloco <Tabs> quando uma tarefa roda em mais de uma interface, painel do Console primeiro, um procedimento completo por painel.
• Um aside com o caminho alternativo, quando a tarefa genuinamente ramifica.

Template

Copie o template e substitua cada <placeholder>.

Separe as seções principais da página com uma régua ---, e nunca coloque uma logo depois do frontmatter.

Regras

• Nomeie a tarefa no título. Uma frase verbal curta no imperativo: Criar um bucket, Alterar as permissões de um bucket. Não um gerúndio, não uma pergunta, não um prefixo Como ... — o verbo carrega o título. O prefixo está aposentado em páginas novas e reescritas.
• Abra com uma frase de escopo. Declare o que a página permite ao leitor fazer e a partir de onde: Você pode criar um bucket pelo Azion Console, pela Azion CLI ou pela API.
• Uma tarefa por heading. Um heading que cobre duas tarefas vira dois headings.
• Acrescente informação depois de cada heading. A primeira frase de uma seção de tarefa deve acrescentar informação que o heading não dá; o lead-in carrega a seção.
• Siga as regras de passos. Os passos seguem Procedimentos, e todo procedimento termina com sua frase de resultado.
• 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.
• Ramifique onde a tarefa ramifica. Tarefas com mais de uma interface usam um bloco <Tabs>, painel do Console primeiro — nunca seções sequenciais por interface.
• Não ensine. Uma frase de contexto, depois os passos. Um parágrafo de contexto pertence a uma página de conceito; aponte para ela.
• Use um verbo por ação, em todas as menções da página.
• Aponte para os vizinhos. Guias how-to irmãos e a página de referência do produto, no corpo ou em ## Próximos passos.
• Mande um objetivo que cruza produtos para um guia multiproduto.
• Aponte para fora em produtos de terceiros. Nomeie o passo do fornecedor; não documente a interface dele.

Exemplos

O trecho a seguir mostra a frase de escopo, os pré-requisitos e o painel do Console da primeira tarefa:

• Crie regras de request e response: duas tarefas em uma página, cada uma com passos numerados e imperativos.

Relacionados