WtD Prague: The perfect error message

This week I’m attending Write the Docs Prague. It’s super exciting to attend a European Write the Docs conference, and to be visiting the lovely city of Prague. This post contains my notes from a talk at the conference. All credit goes to the presenter, any mistakes are my own.

James Scott’s presentation was “How to write the perfect error message”. Error messages are micro-copy, but they deserve more attention than they get. Bad error messages can result in unhappiness and in bad reports on social media.

Error messages are intended to help users make sense of complex technology. But often the text is so bad that it just increases the confusion.

An error message has three parts: The notification something went wrong, the cause of the error, and what the user can do to resolve the problem.

When writing an error message:

• Consider your audience.
• Be humble. Don’t assume the user has caused the error. Apologize if necessary. James added a caveat that you should only apologize if the error has caused a big problem, as too many apologies are distracting.
• Don’t use words like “illegal” and “fatal”. Avoid accusatory language that makes the user feel bad.
• Be helpful. Give the user some information about what to do next. For example, ask people to try again, and give a link to the help centre.
• Keep the text short. Remember that people tend not to read long text. Also, some people may find it hard to understand long messages.
• Avoid jargon. Speak to people in the language they understand, and show empathy with the user.
• Be careful with humour in error messages. Bear in mind that people may be upset already when they receive the error, or may not understand the joke. Jokes can grow tired if an error keeps occurring. Jokes may not translate well into other languages.
• Consider the colour of the error box. Colours have different connotations in different cultures. Red, for example, is associated with danger in western countries but in China it’s associated with good luck and positive events. Also consider accessibility: colour blindness may prevent people from distinguishing colours.
• Focus on accessibility of error messages. Place your errors on top of a form so people can find them more easily. Use clear language, and make sure the error message is available to accessibility tools. James mentioned the ARIA (Accessible Rich Internet Applications) standard. James recommends www.a11yproject.com for accessibility resources.

James showed us some bad error messages (always good for a laugh) and made suggestions on how each of them could be better.

Thank you James for an informative, amusing talk on error messages.