Resolver Solucionar
Diagnosticar e resolver problemas de forma eficiente, muitas vezes sob pressão.
Esbarrar em problemas, seja por configurações incorretas, casos extremos ou erros reais, é uma experiência comum para os usuários. A ação Resolver representa a necessidade de diagnosticar e resolver dificuldades de forma eficiente, muitas vezes sob pressão, quando os sistemas falham ou os prazos se aproximam.
Exemplos de documentação dedicada à resolução de problemas incluem Debug Pods do Kubernetes e Troubleshooting do Elasticsearch. A documentação mais eficaz vai além de enumerar problemas comuns e soluções: ensina os usuários a raciocinar sobre o sistema quando ele não funciona como esperado.
Pode ser tentador considerar essa documentação um recurso meramente reativo, mas ela pode transformar a confiança dos usuários. Quando as pessoas entendem como se recuperar de falhas, ficam mais dispostas a explorar e a ultrapassar limites, sabendo que têm uma rede de segurança à qual podem recorrer.
O que o usuário quer fazer
Esbarrar em problemas — configurações incorretas, casos extremos ou erros reais — é comum. A resolução de problemas representa a necessidade de diagnosticá-los e resolvê-los de forma eficiente, muitas vezes sob pressão, quando os sistemas falham ou os prazos se aproximam.
Sinais de que a documentação não atende a essa necessidade
- Os chamados de suporte repetem a mesma pergunta e a resposta está no histórico de uma conversa, não na documentação.
- As mensagens de erro aparecem no código, mas nunca na documentação.
- Os usuários procuram uma mensagem de erro e chegam a uma página que não a menciona.
Dois exemplos reais
Tipos de conteúdo comuns
| DITA | Diátaxis | Good Docs Project |
|---|---|---|
| <troubleshooting>, <trouble>, <cause>, <remedy> | Guia prático (orientado ao problema) | Guia de resolução de problemas |
Uma métrica
tempo de resolução · Tempo mediano entre o sintoma e a volta a um estado funcional.