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.