Mayel
@mayel  ·  activity timestamp 3 years ago
help the audience to understand what they can do to recover from an issue

I read a blog recently from an organisation boasting that their average time to resolve tech support request went up over the years, because they adapted their software and UX to avoid most of the simpler and/or common issues that came up from ever happening again, and so issues that still appeared were often more complex or unique. I think it's a similar situation, were the errors I listed are placeholder for unexpected issues, in that we haven't yet encountered them and/or taken the time to code guardrails or write unit tests to avoid them from happening or at least to detect them and show more specific and helpful error messages.

For context, the tech stack we're using has a philosophy of "let it crash" which comes from Erlang and is reflected in how LiveView (the UI framework we use) handles errors as well. By default doesn't show any error message for unexpected errors (it just reloads the page). Most of the errors I pasted are ones that we instead infer from looking at the crash details to show something that can help with debugging...

Mayel
@mayel  ·  activity timestamp 3 years ago

We've indeed seen and discussed that article 😊 It has some good suggestions though seems mostly focused on errrors related to user input (like in forms, which is something we could/should quite easily improve in Bonfire).


I'd also like feedback on how we could improve messages related to unexpected or general errors, such as due to or untested edge case. For example:

  • You seem to have provided an incorrect data type (eg. an invalid ID)
  • You seem to be referencing an invalid object ID, or trying to insert duplicated data
  • The data provided caused an unexpected error and could do not be inserted or updated
  • The data provided seems invalid and could not be inserted or updated
  • Invalid arguments passed
  • The function post/2 in module Posts didn't receive data in a format it can recognise
  • A function didn't receive data in a format it could recognise
  • A with condition didn't receive data in a format it could recognise
  • A case condition didn't receive data in a format it could recognise
  • A condition didn't receive data that matched a format it could recognise
  • Could not complete this action
  • Could not complete this request
  • The app encountered an unexpected error
  • An exceptional error caused the operation to stop
  • An exceptional error was thrown
  • An exceptional error occurred
  • Something went wrong
  • Oops, this resulted in something unexpected
  • You need to log in first
  • Not found
  • You do not have permission to [...]
  • We couldn't find an account with the details you provided
  • This site is by invitation only
  • This link or token has expired, please request a fresh one
  • This link or token was already used, please request a fresh one if necessary
  • This token was not found, please request a fresh one
  • This user account is disabled. Please contact the instance administrator
  • Please confirm your email address first
  • Reset your password to login
  • User not found
  • Could not delete
  • Bad request: malformed header
  • Unknown resource


You'll notice many of these are similar, but because they for different reasons wording them differently helps us identify the problem when reported.

Ryuno-Ki
@RyunoKi  ·  activity timestamp 3 years ago

Ah, that's great!


Hm, when I would be tasked with wording them, I would imagine, how it would be situated in meatspace.


Like, you couldn't suffessfully submit something. I imagine a waiter getting back to you, apologising and informing you, that you order couldn't be fulfilled (something was missing - what exactly? your dish is out etc). Basically, avoid jargon, help the audience to understand what they can do to recover from an issue.


Forms are the basic kind of interaction between someone entering information and the service responding to it. That's why you will most likely see error messages in this context.
Mayel
@mayel  ·  activity timestamp 3 years ago
help the audience to understand what they can do to recover from an issue

I read a blog recently from an organisation boasting that their average time to resolve tech support request went up over the years, because they adapted their software and UX to avoid most of the simpler and/or common issues that came up from ever happening again, and so issues that still appeared were often more complex or unique. I think it's a similar situation, were the errors I listed are placeholder for unexpected issues, in that we haven't yet encountered them and/or taken the time to code guardrails or write unit tests to avoid them from happening or at least to detect them and show more specific and helpful error messages.

For context, the tech stack we're using has a philosophy of "let it crash" which comes from Erlang and is reflected in how LiveView (the UI framework we use) handles errors as well. By default doesn't show any error message for unexpected errors (it just reloads the page). Most of the errors I pasted are ones that we instead infer from looking at the crash details to show something that can help with debugging...

Mayel
@mayel  ·  activity timestamp 3 years ago

So just to answer this more directly:

help the audience to understand what they can do to recover from an issue

In many cases for unexpected errors there's not much to do other than try it again, or report the error (which the button under the error message prompt to do) with as much details as possible.