Criar mensagens de erro acionáveis

Esta página descreve as práticas recomendadas para escrever mensagens de erro úteis que informam ao usuário como corrigir o problema para que ele possa concluir o objetivo.

Quando um usuário interage com um app do Google Chat, encontrar mensagens de erro pode ser uma experiência frustrante quando o erro não é útil. Por exemplo, a mensagem de erro An error occurred não é útil porque não explica o que deu errado, como o usuário pode corrigir o problema ou como ele pode receber ajuda. Esta página descreve como estruturar mensagens de erro para que elas sejam úteis aos usuários, mostrando exemplos úteis e inúteis.

Estrutura da mensagem de erro

Uma mensagem de erro útil tem a seguinte estrutura:

  • O que deu errado. Dizer por que o app do Chat não pode concluir uma solicitação ajuda o usuário a resolver o problema. Explicar por que ocorreu um erro gera confiança.
  • Como o usuário pode prosseguir para alcançar o objetivo. Não basta apenas dizer o que deu errado. Informe aos usuários como eles podem superar o erro e concluir a meta.
  • Como receber ajuda. Se o usuário ainda estiver preso, informe como ele pode receber mais ajuda. Pode ser um comando /help ou um link para a documentação do app do Chat.

Exemplo de mensagem de erro: formato de data incorreto

Neste exemplo, o usuário inseriu uma data em um formato que o app do Chat não esperava. Ele escreveu November 19, 2021, mas o app do Chat espera 2021-11-19.

Confira uma versão útil e uma versão inútil da mensagem de erro que o app do Chat responde:

Erro útil

Um usuário pede ao app do Chat para agendar uma reunião com outra pessoa. O app do Chat responde com uma mensagem de erro útil:

I don't recognize the date format you entered. Write dates as `yyyy-mm-dd`; for example, `2000-01-31`. For help, type `/help`.

Exemplo de mensagem de erro que informa ao usuário o que deu errado, como proceder e como receber ajuda.

Essa mensagem de erro é útil pelos seguintes motivos:

  • Diz o que deu errado. O app do Chat não reconhece o formato de data.
  • Explica como corrigir o erro informando ao usuário o formato de data esperado e oferece um exemplo de data que ajuda as pessoas a entender o que escrever.
  • Oferece mais ajuda com um comando de barra /help. Se os usuários ainda estiverem presos, eles saberão como aprender mais.

Erro inútil

Um usuário pede ao app do Chat para agendar uma reunião com outra pessoa. O app do Chat responde com uma mensagem de erro inútil:

Enter the correct date format.

Exemplo de mensagem de erro que não fornece informações úteis.

Essa mensagem de erro é inútil pelos seguintes motivos:

  • Não diz se agendou a reunião. O usuário pode hesitar em reagendar a reunião ou presumir que ela foi agendada.
  • Não informa ao usuário como formatar a data. Em vez de presumir que os usuários sabem como formatar a data, ela deve dizer que espera o formato de data yyyy-mm-dd.
  • Não oferece mais ajuda. Quando os usuários estão presos e não sabem como prosseguir, eles podem parar de enviar mensagens para o app do Chat.

Faça um teste

Agora que você sabe como escrever erros úteis, consegue identificar no cenário a seguir qual desses erros é útil:

Um app do Chat cria eventos do Google Agenda quando os usuários enviam mensagens para o app do Chat com a palavra-chave schedule. Para criar um evento do Google Agenda, o app do Chat exige a autenticação do usuário. Se um usuário não tiver sido autenticado, o app do Chat responderá com uma mensagem de erro.

Qual mensagem de erro é útil?
Before I can schedule the meeting, you must sign in by typing /signin. To learn more, type /help.
Essa mensagem de erro é útil porque diz o seguinte:
  • O que deu errado. O app do Chat exige autenticação.
  • Como prosseguir. Digite /signin para autenticar.
  • Como receber ajuda. Se o usuário quiser mais informações, ele poderá digitar /help.
You must authenticate.
Essa mensagem de erro é inútil porque não diz como autenticar.
Sign in.
Essa mensagem de erro é inútil porque não diz como fazer login e implica que o usuário está desconectado em vez de dizer isso claramente, o que é confuso.
Can't schedule meeting.
Essa mensagem de erro é inútil porque não informa ao usuário por que a reunião não pode ser agendada ou como o usuário pode prosseguir. Nenhuma ajuda é fornecida.