Criar mensagens de erro acionáveis

Nesta página, descrevemos as práticas recomendadas para escrever mensagens de erro acionáveis que informem ao usuário como corrigir o problema para que ele possa concluir a meta.

Quando um usuário interage com um app do Google Chat, encontrar mensagens de erro pode ser uma experiência frustrante se o erro não for acionável. 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 de ações e inações.

Estrutura da mensagem de erro

Uma mensagem de erro útil tem a seguinte estrutura:

• O que deu errado. Explicar por que o app de chat não pode 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 avançar em direção à meta. Nunca é suficiente apenas dizer o que deu errado. Diga aos usuários como superar o erro e concluir a meta.
• Como receber ajuda. Se o usuário ainda estiver com dificuldades, diga 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 Chat não esperava. Eles escreveram November 19, 2021, mas o app Chat espera 2021-11-19.

Confira uma versão prática e outra não prática da mensagem de erro com 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 Chat responde com uma mensagem de erro útil e prática:

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

Essa mensagem de erro é ú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 dificuldades, eles saberão como saber mais.

Erro sem ação

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

Enter the correct date format.

Essa mensagem de erro não pode ser corrigida pelos seguintes motivos:

• Não informa se a reunião foi agendada. O usuário pode hesitar em remarcar 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, é melhor dizer que o formato esperado é yyyy-mm-dd.
• Não oferece mais ajuda. Quando os usuários ficam presos e não sabem como continuar, 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 deles é acionável:

Um app do Chat cria eventos da 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 é útil?

Antes de agendar a reunião, faça login digitando /signin. Para saber mais, digite /help.

Essa mensagem de erro é útil porque diz o seguinte:

• O que deu errado. O app Chat requer autenticação.
• Como proceder. Digite /signin para autenticar.
• Como receber ajuda. Se o usuário quiser mais informações, ele pode digitar /help.

Você precisa fazer a autenticação.

Essa mensagem de erro não pode ser corrigida porque não diz como fazer a autenticação.

Faça login.

Essa mensagem de erro não é útil porque não informa como fazer login e implica que o usuário está desconectado em vez de dizer isso claramente, o que é confuso.

Não é possível programar uma reunião.

Essa mensagem de erro não é útil porque não informa ao usuário por que a reunião não pode ser agendada nem como ele pode proceder. Nenhuma ajuda é fornecida.