Resolver Solucionar
Diagnosticar e resolver problemas de forma eficiente, muitas vezes sob pressão.
Deparar-se com problemas, seja devido a configurações incorretas, casos extremos ou erros reais, é uma experiência comum para os utilizadores. 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 utilizadores a raciocinar sobre o sistema quando este não funciona como esperado.
Pode ser tentador considerar esta documentação um recurso meramente reativo, mas ela pode transformar a confiança dos utilizadores. Quando as pessoas compreendem como recuperar de falhas, ficam mais dispostas a explorar e a ultrapassar limites, sabendo que têm uma rede de segurança a que podem recorrer.
O que o utilizador quer fazer
Deparar-se com configurações incorretas, casos extremos ou erros reais é comum. A resolução de problemas representa a necessidade de os diagnosticar e resolver 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 responde a esta necessidade
- Os pedidos de apoio repetem a mesma pergunta, e a resposta encontra-se 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 utilizadores 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 para o problema) | Guia de resolução de problemas |
Uma métrica
tempo de resolução · Tempo mediano entre o sintoma e a recuperação de um estado funcional.