Diretrizes de mensagem de erro
Uma mensagem de erro é um texto exibido para descrever um problema que está impedindo o usuário ou o sistema de concluir uma tarefa. O problema pode resultar em corrupção ou perda de dados. Outros tipos de mensagem incluem confirmações, avisos e notificações. As diretrizes neste tópico destinam-se a ajudá-lo a escrever mensagens de erro claras fáceis de localizar e úteis para os clientes.
Mensagens de erro mal escritas podem ser uma fonte de frustração para os usuários e podem aumentar os custos de suporte técnico. Uma mensagem de erro bem escrita fornece as seguintes informações ao usuário:
- O que aconteceu e por quê?
- Qual é o resultado final para o usuário?
- O que o usuário pode fazer para evitar que isso aconteça novamente?
O comprimento do texto não é um problema desde que o desenvolvedor trate os tamanhos do buffer corretamente. É importante que o usuário tenha todas as informações necessárias para resolver o problema. Se uma mensagem tiver vários públicos, talvez seja necessário fornecer texto separado para administradores, usuários finais e desenvolvedores.
Práticas recomendadas
Veja a seguir maneiras de melhorar suas mensagens de erro:
- Evite condições de erro. Se você puder prever que ocorrerá um erro quando um usuário executar uma ação específica, reescreva seu código para que o usuário não possa causar o erro.
- Escreva uma mensagem de erro separada para cada causa conhecida do erro. Não use uma única mensagem genérica para explicar todos os motivos possíveis para o erro, a menos que você não possa determinar a causa do erro quando ele ocorrer.
- Declare o problema claramente e, se ele for útil para o usuário, explique o que causou o problema. Sempre que possível, substitua as mensagens genéricas dos recursos da tabela de mensagens do sistema por uma mensagem detalhada específica para o problema.
- Forneça ao usuário uma solução para o problema. Se a solução tiver mais de uma etapa, consulte um tópico de ajuda que explica a tarefa em detalhes.
- Exiba apenas o produto, o componente ou o nome do assistente na barra de título da mensagem. Isso ajuda o usuário a determinar onde está o problema. Não resumir o problema na barra de título ou incluir a palavra "erro".
- Não use jargões técnicos, use a terminologia que seu público entende. Não use gírias ou abreviações.
- Use os botões de comando apropriados, como OK, Cancelar, Sim, Não e Repetir. Você pode usar combinações desses botões. Os botões Sim e Não sempre devem ser usados em combinação e sempre devem ser precedidos por uma pergunta.
- Para interromper uma operação e fechar a caixa de mensagem, use o botão Cancelar.
- Para fechar uma caixa de mensagem, use o botão fechar .
- Para fornecer mais informações sobre a causa do erro, use o botão Detalhes.
- Para fornecer mais informações sobre a solução para o problema, use o botão Ajuda.
- Se uma ação do usuário estiver incluída na mensagem, use o botão OK para fechar a caixa de mensagem.
- Sim e Não botões devem ser usados em combinação e sempre devem ser precedidos por uma pergunta.
- Se o erro for um erro crítico, escreva-o no log de eventos .
Considerações de estilo
- Use frases completas, mas simples.
- Use o tempo presente para descrever as condições que causaram o problema ou um estado que ainda existe. Você pode usar o tempo passado para descrever um evento distinto que ocorreu no passado.
- Use a voz ativa sempre que possível. Você pode usar a voz passiva para descrever a condição de erro.
- Evite pontos de exclamação e texto em letras maiúsculas.
- Não faça o usuário se sentir culpado mesmo que o problema seja resultado de um erro do usuário.
- Não antropomorfize. Não implica que programas ou hardware possam pensar ou sentir.
- Não use palavras ou frases coloquiais. Não use termos que possam ser ofensivos em determinadas culturas.
- Não complica vários substantivos sem adicionar uma preposição ou subclausa para esclarecer o significado. Por exemplo, "Servidor de diretório do Serviço LDAP do Servidor do Site" deve ser alterado para "Servidor de diretório para o Serviço LDAP do Servidor do Site".
- Insira descritores antes de um termo para esclarecer o significado da frase. Por exemplo, "Especificar InfID quando Detect é definido como Não". Deve ser alterado para "Especificar o parâmetro InfID quando a opção Detectar for definida como Não".
- Evite a palavra "ruim". Use termos mais descritivos para informar ao usuário o que está errado. Por exemplo, evite mensagens como "Tamanho ruim". Em vez disso, informe ao usuário quais critérios usar ao especificar um tamanho.
- Evite a palavra "por favor". Pode ser interpretado para significar que uma ação necessária é opcional.
- Coloque palavras que estejam no índice e relevantes para o significado central no início da cadeia de caracteres da mensagem.