Criar mensagens de erro acionáveis

Esta página descreve as práticas recomendadas para escrever mensagens de erro acionáveis que informam ao usuário como corrigir o problema para que ele possa concluir a tarefa.

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 pode ser resolvido. 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 sejam úteis aos usuários mostrando exemplos acionáveis e não acionáveis.

Estrutura da mensagem de erro

Uma mensagem de erro acionável tem a seguinte estrutura:

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

Exemplo de mensagem de erro: formato de data incorreto

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

Confira uma versão acionável e inativa da mensagem de erro que o app Chat responde:

Erro acionável

Um usuário pede ao app Chat para agendar uma reunião com outra pessoa. O app de 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 pode ser útil pelos seguintes motivos:

  • Diz o que deu errado. O app Chat não reconhece o formato da data.
  • Explica como corrigir o erro informando ao usuário o formato de data esperado e dá 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 com dúvidas, eles saberão como aprender mais.

Erro sem ação

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

Enter the correct date format.

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

Esta mensagem de erro não pode ser resolvida pelos seguintes motivos:

  • Não diz se a reunião foi agendada. O usuário pode hesitar em remarcar a reunião ou pode 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, é necessário informar que o formato de data yyyy-mm-dd é esperado.
  • Não oferece mais ajuda. Quando os usuários ficam presos e não sabem como prosseguir, eles podem parar de enviar mensagens para o app Chat.

Faça um teste

Agora que você sabe como escrever erros acionáveis, identifique no cenário a seguir qual desses erros é acionável:

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

Qual mensagem de erro pode ser usada?
Antes de programar a reunião, você precisa fazer login digitando /signin. Para saber mais, digite /help.
Esta mensagem de erro pode ser resolvida porque informa o seguinte:
  • O que deu errado. O app de chat requer autenticação.
  • Como proceder. Digite /signin para fazer a autenticação.
  • Como receber ajuda. Se o usuário quiser mais informações, ele pode digitar /help.
Você precisa fazer a autenticação.
Esta mensagem de erro não pode ser resolvida porque não informa como fazer a autenticação.
Faça login.
Essa mensagem de erro não pode ser resolvida porque não informa como fazer login e implica que o usuário está desconectado em vez de dizer claramente isso, o que é confuso.
Não foi possível programar a reunião.
Essa mensagem de erro não pode ser resolvida porque não informa ao usuário por que a reunião não pode ser programada ou como o usuário pode prosseguir. Nenhuma ajuda é fornecida.