Guias multirrecurso

Propósito

Um guia multirrecurso leva o leitor a um objetivo que nenhum recurso da plataforma alcança sozinho. Ele aplica a forma base de how-to.

Outros conjuntos de documentação dividem esse tipo em guias de solução, guias de design e guias de implementação. Esta documentação usa um nome e um conjunto de regras, porque os três descrevem a mesma página.

Quando usar

Escreva um guia multirrecurso quando:

• O objetivo precisa de dois ou mais recursos da plataforma, e nenhuma seção de recurso da plataforma é dona dele.
• O leitor pensa em resultados, como proteger um checkout, e não em nomes de recurso da plataforma.
• Um guia de um único recurso da plataforma fica mandando o leitor para outro recurso da plataforma no meio da tarefa.

Não escreva um guia multirrecurso quando:

• Um recurso da plataforma alcança o objetivo. Escreva um guia how-to na seção daquele recurso da plataforma.
• O leitor quer entender o design em vez de construí-lo. Escreva uma página de arquitetura.
• O objetivo é um caso de uso do catálogo. Isso é um caso de uso, e usa a mesma forma base com um cenário e uma tabela de requisitos.

Registro

Procedural: 20 palavras por frase, uma instrução por passo, imperativo e ativo. Tom: diretivo, claro, decidido. Estrutura de frases tem as regras.

Estrutura

Componentes obrigatórios

• Abertura pelo problema: uma ou duas frases declaram o problema, antes de qualquer nome de recurso da plataforma. Os recursos da plataforma, e os produtos configurados neles, entram depois do problema, pelo papel: “Você configura o cache na aplicação e a filtragem de requisições no firewall.”
• Pré-requisitos: uma seção ## Pré-requisitos, em lista; cada item é um link ou um comando de uma linha. Um único pré-requisito é uma frase, não uma lista.
• Etapas: um ## por etapa do fluxo, nunca por recurso da plataforma, cada um com um título imperativo que nomeia a etapa. Cada etapa nomeia seu recurso da plataforma na entrada, contém um procedimento comum e se sustenta sozinha.
• 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 card por destino: o título, o link e o motivo como texto do card.

Componentes opcionais

• Uma tabela de recursos da plataforma: o que cada recurso da plataforma contribui, quando há mais de três envolvidos.
• Um diagrama: quando a ordem das peças é difícil de segurar em texto. Aponte para a página de arquitetura quando existir uma.

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 o objetivo, não os recursos da plataforma. O título declara o objetivo em linguagem simples, sem nomes de recurso da plataforma: Sirva um site com conteúdo em cache e um checkout protegido. O leitor busca pelo resultado.
• Declare o problema primeiro. Uma ou duas frases, depois os recursos da plataforma, e os produtos configurados neles, pelo papel: “Você configura o cache na aplicação e a filtragem de requisições no firewall.”
• Ordene pelo fluxo, nunca pelo catálogo de recursos da plataforma. Uma página organizada um recurso da plataforma por vez é um pacote de guias how-to com um só título.
• Nomeie o recurso da plataforma em cada etapa. Um nome de interface sem qualificação fica ambíguo quando a página cruza recursos da plataforma.
• Continue sendo um how-to. Os recursos da plataforma são a rota, não o assunto. Um parágrafo de contexto de recurso da plataforma pertence a uma página de conceito; aponte para ela.
• Siga as regras de passos. Os passos seguem Procedimentos, e todo procedimento termina com sua frase de resultado.
• Mostre a saída 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.
• Comprometa-se com um caminho recomendado. Alternativas vão em um aside, nunca como bifurcações nos passos.
• Verifique o caminho inteiro. Esses guias falham nas emendas, então cheque o resultado e não o último passo.
• Aponte para os vizinhos. Os guias how-to e a página de referência de cada recurso da plataforma, no corpo ou em ## Próximos passos.

Exemplos

O trecho a seguir mostra a abertura pelo problema, os pré-requisitos e a primeira etapa do fluxo:

Relacionados