Páginas de troubleshooting

Propósito

Uma página de troubleshooting corrige um sintoma que o leitor está vendo agora. Ela aplica a forma base de guia how-to: a tarefa é uma correção.

Quando usar

• Escreva uma página de troubleshooting quando uma falha conhecida tem uma correção que o leitor aplica sozinho.
• Escreva uma página para um grupo de sintomas relacionados, com uma seção por sintoma.
• Não escreva uma página de troubleshooting para uma tarefa que o leitor planeja. Uma tarefa planejada precisa de um guia how-to.
• Não escreva uma página quando o produto funciona como projetado. As razões de um design pertencem a uma página de conceito.
• Não escreva uma página quando a única correção é um ticket de suporte. Uma página cujo único passo é “abra um ticket” é um link, não uma página.

Registro

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

Estrutura

O título tem a forma Troubleshoot <recurso ou classe de sintomas> em inglês e Solução de problemas de <recurso ou classe de sintomas> em português.

Componentes obrigatórios

• Abertura: uma frase de escopo que nomeia o produto e a classe de sintomas que a página cobre.
• Seções de sintoma: uma seção ## por sintoma, cada uma autossuficiente e legível em qualquer ordem.
• Headings de sintoma: uma frase nominal que declara o comportamento observável, com a mensagem de erro citada literalmente como texto simples: ## 403 Forbidden em requisições legítimas. Sem código inline em heading: as crases renderizam um chip de código que quebra a linha do heading.
• O sintoma: o que o leitor vê, em uma ou duas frases, primeiro em cada seção.
• A causa: o que produz o sintoma.
• A correção: um procedimento numerado, ou marcadores na forma **<Nome da solução>**: o que ela faz e seu link.
• O resultado: o que o leitor deve ver agora, fechando cada seção.
• Recursos relacionados: um fechamento ## Recursos relacionados, uma lista de DocItem com os guias how-to e as páginas de referência em que as correções se apoiam.

Componentes opcionais

• Saída de erro: a mensagem ou a tela que confirma que o leitor tem esse sintoma.
• Contato com o suporte: um aside que aponta o caminho do suporte, depois de todas as correções.

Template

Copie o template e substitua cada <placeholder>:

Separe as seções de sintoma com uma linha --- e nunca coloque uma imediatamente depois do bloco de frontmatter.

Regras

• Nomeie a página pela classe de sintomas. O título tem a forma Troubleshoot <recurso ou classe de sintomas>.
• Abra com uma frase de escopo que nomeia o produto e a classe de sintomas que a página cobre.
• Nomeie o sintoma, não a causa. O leitor busca com o que ele vê. Cite as mensagens de erro literalmente: no corpo em monospace, em um heading como texto simples, porque as crases renderizam um chip de código que quebra a linha do heading.
• Faça cada seção de sintoma ficar de pé sozinha. O leitor chega a qualquer seção primeiro; nomeie o assunto em cada uma.
• Mantenha a ordem dentro de cada seção: o sintoma, a causa, a correção, o resultado.
• Ordene as causas por frequência. Quando um sintoma tem mais de uma causa, o leitor tenta as correções de cima para baixo.
• Escreva as correções como passos numerados e imperativos conforme Procedimentos, ou como marcadores na forma **<Nome da solução>**: o que ela faz e seu link.
• Aponte procedimentos longos em vez de repeti-los. A correção contém o que é específico do sintoma; o caminho genérico é um link.
• Feche com ## Recursos relacionados: uma lista de DocItem com os guias how-to e as páginas de referência em que as correções se apoiam. Um aside de suporte pode vir antes.
• Posicione pelo escopo. Problemas da plataforma em Suporte, problemas de produto nos guias daquele produto.

Exemplos

Este exemplo, em inglês, mostra a abertura e a primeira seção de sintoma de uma página de troubleshooting sobre falsos positivos do WAF:

Relacionados