Diretrizes de mensagem de erro

  • Artigo

Uma mensagem de erro é o texto que é exibido para descrever um problema que ocorreu 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 que são 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 para o 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 manipule os tamanhos de 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

A seguir estão 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.
  • Indique o problema claramente e, se 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.
  • Fornecer 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 nome do produto, componente ou assistente na barra de título da mensagem. Isso ajuda o usuário a determinar onde está o problema. Não resuma o problema na barra de título ou inclua a palavra "erro".
  • Não use jargões técnicos, use terminologia que seu público entenda. 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 devem ser sempre usados em combinação e devem ser sempre precedidos de 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.
    • Os botões Sim e Não devem ser usados em combinação e devem ser sempre precedidos de uma pergunta.
  • Se o erro for crítico, grave-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 pretérito para descrever um evento distinto que ocorreu no passado.
  • Use voz ativa sempre que possível. Você pode usar a voz passiva para descrever a condição de erro.
  • Evite texto em maiúsculas e pontos de exclamação.
  • Não faça o usuário se sentir culpado, mesmo que o problema seja o resultado de um erro do usuário.
  • Não antropomorfize. Não implique 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 componha vários substantivos sem adicionar uma preposição ou subcláusula para esclarecer o significado. Por exemplo, "Site Server LDAP Service directory server" deve ser alterado para "Directory server for the LDAP Service of the Site Server".
  • Insira descritores antes de um termo para esclarecer o significado da frase. Por exemplo, "Especificar InfID quando Detectar estiver definido como Não." deve ser alterado para "Especificar o parâmetro InfID quando a opção Detectar estiver definida como Não".
  • Evite a palavra "ruim". Use termos mais descritivos para dizer ao usuário o que está errado. Por exemplo, evite mensagens como "Tamanho incorreto". Em vez disso, diga ao usuário quais critérios usar ao especificar um tamanho.
  • Evite a palavra "por favor". Pode ser interpretado como significando que uma ação necessária é opcional.
  • Coloque palavras que estão no índice e são relevantes para o significado central no início da cadeia de caracteres da mensagem.