Guias multiproduto

Propósito

Um guia multiproduto leva o leitor a um objetivo que nenhum produto sozinho alcança. 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 multiproduto quando:

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

Não escreva um guia multiproduto quando:

• Um produto alcança o objetivo. Escreva um guia how-to na seção daquele produto.
• 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 produto. Os produtos, e os recursos em que são configurados, 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 produto, cada um com um heading imperativo que nomeia a etapa. Cada etapa nomeia seu produto 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 produtos: o que cada produto 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 produtos. O título declara o objetivo em linguagem simples, sem nomes de produto: 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 produtos e os seus recursos 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 produtos. Uma página organizada produto a produto é um pacote de guias how-to com um só título.
• Nomeie o produto em cada etapa. Um nome de interface sem qualificação fica ambíguo quando a página cruza produtos.
• Continue sendo um how-to. Os produtos são a rota, não o assunto. Um parágrafo de contexto de produto 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 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.
• 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 produto, no corpo ou em ## Próximos passos.

Exemplos

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

Relacionados