My thoughts and favorite points of someone else’s writing from the web:
When life gives you lemons, write better error messages
By: Jenni Nadler
Wix also has a second article on this topic specifically from a UX point of view.
What makes a bad error message
Section titled: What makes a bad error message
-
Inappropriate tone: That is not the time to be cutesy or fluffy. We want to show the users that we know it’s serious and we understand it’s important to them. A good rule of thumb when writing error messages is to think: “Would I actually verbalize these words to a real person?”. Stop it with “Oops! Something went wrong…”.
-
Technical jargon
-
Passing the blame: Try to focus on the problem, rather than the action that led to the problem. We don’t want to shame users, even if something they did is why they’re seeing a certain error message.
- Avoid using phrases like “you did” or “you failed to do”. Instead, take the blame gracefully; explaining that you “can’t find” the missing information.
- Even passing the blame to 3rd parties can make you look unprofessional.
-
Generic
What makes a good error message
Section titled: What makes a good error message
-
Clear and specific: Users shouldn’t have to guess what’s wrong with the product they’re using. Clearly describe:
- what the error is
- why it happened
- and when possible, how the user can overcome the problem
-
Provide reassurance: Where possible, let them know what was not affected by the error. For example, were their changes still saved as a draft, even though their email wasn’t sent?
- When presenting an error that’s due to something a user “can’t” do, it may be beneficial to provide suggestions of actions they can perform.
-
Be empathetic: But not overly apologetic
-
Always give a way out: If they can’t fix the problem, or if it’s possible the issue could keep happening, provide them with a way to contact Customer Care.
Examples
Section titled: ExamplesGood example
Section titled: Good example“Can’t rename “Photos” because another file with that name already exists. Please choose a different name.
- What the error is: a rename error
- Why it happened: because another file with that name exists
- How the user can overcome it: by specifying a different name.
- The error message is specific enough, so that the issue doesn’t turn into an insurmountable obstacle.
Bad example
Section titled: Bad example“Requested Range is not Satisfiable. Request-header field (section 14.35) missing and cannot be completed.
[OK button at the bottom of the dialog]
Here the user is presented with an error that contains meaningless jargon and no way to overcome the error. The only action the user is presented with is to hit “OK.” Clearly, in this case, an “unrecoverable error” is not ok.
Good error messages require more context
Section titled: Good error messages require more contextThe reason we see so many “oops” and “something went wrong” error messages is because once an error has bubbled up through your entire application to your outermost catch (error boundary), you’ve lost any and all context about what that error is, why it happened, and what can be done about it.
The best error messages happen when the error is checked for immediately after a specific operation. In addition to helping your users, this strategy is also guaranteed to make your software work better. It’s also the topic of my other post Why software doesn’t work anymore.