Use as seções de solução de problemas em guias ou artigos de procedimentos para manter as soluções próximas aos procedimentos. Trabalhe com os gerentes de produtos e o suporte para identificar erros comuns e incluí-los na documentação.
Problemas conhecidos
Problemas conhecidos são um subconjunto do conteúdo de solução de problemas especificamente projetado para responder a bugs, problemas de experiência do usuário/interface do usuário e outras peculiaridades do produto que geram um alto volume de tíquetes de suporte. Enquanto o conteúdo de solução de problemas pode descrever os erros que as pessoas poderão encontrar, os problemas conhecidos explicam os problemas que as pessoas vão encontrar.
Assim como todo o conteúdo de solução de problemas, os problemas conhecidos podem ser uma seção de um artigo ou um artigo autônomo. Se um problema conhecido se aplicar a um artigo específico, documente-o nesse artigo. Se um problema conhecido se aplicar a um conjunto específico de artigos ou a um agrupamento conceitual de recursos ou se um produto ou um recurso tiver vários problemas conhecidos que devem ser agrupados, crie um artigo dedicado intitulado "Problemas conhecidos no NOME".
O conteúdo do problema conhecido de um produto ou de um recurso não precisa ser abrangente. Ao contrário de outros tipos de conteúdo de solução de problemas, alguns problemas conhecidos podem não ter soluções alternativas. O objetivo de documentar um problema sem uma solução alternativa é ajudar as pessoas a confirmar se o problema existe e economizar tempo procurando uma solução que ainda não existe depois que o GitHub já determinou que não há uma solução alternativa.
Os PMs e os EMs (proprietários de produtos e de recursos) devem ajudar a planejar e revisar o conteúdo do problema conhecido.
Use os problemas conhecidos para explicar as situações a seguir.
- Comportamento do produto que contradiz regularmente às expectativas das pessoas, mas ainda não é priorizado para correção.
- Comportamento que impede regularmente o uso do produto ou do recurso para uma finalidade comum.
- Bugs raros ou graves dos quais o GitHub ainda não priorizou a correção e que não são explicados no produto ou pelo conteúdo existente no GitHub Docs.
Como escrever um conteúdo de solução de problemas
- Use qualquer tipo de conteúdo do GitHub Docs para criar seções de solução de problemas.
- Sempre que possível, mantenha o conteúdo da solução de problemas dentro de um conteúdo de procedimentos ou de guias.
- Você poderá criar um artigo de solução de problemas quando fizer sentido mantê-lo separado, como quando houver um grande volume de conteúdo de solução de problemas sobre um tópico específico.
- Você poderá criar um tópico de mapa de solução de problemas se um produto ou um recurso tiver muitos artigos de solução de problemas, por exemplo, "Solucionar problemas de SSH".
Diretrizes de título para o conteúdo de solução de problemas
- Solução de problemas do RECURSO
- Erro: NOME DO ERRO
- Problemas conhecidos do PRODUTO
Exemplos de conteúdo de solução de problemas
- "Solucionar problemas de SSH"
- "Usar o GitHub Enterprise Server com balanceador de carga"
- "Problemas conhecidos" nas notas sobre a versão do GitHub Enterprise Server
- "Erro: auditoria de chave SSH em andamento"