How to write better error messages

How to write better error messages

Try this simple technique to write messages that help users understand the reason for errors.

How to write better error messages
Image by : 

opensource.com

x

Get the newsletter

Join the 85,000 open source advocates who receive our giveaway alerts and article roundups.

The first time a user encounters an application's documentation, it's not always with the user manual or online help. Often, that first encounter with documentation is an error message.

Technical writers should be involved in writing error messages. It's an important, although often overlooked, part of the job. After all, error messages are documentation, albeit documentation that's embedded in the code.

Why, you ask, should technical writers be involved in creating error messages? Many error messages don't do a good job of helping users. In fact, they often read like they were written by machines for machines. How many times have you run into an error message like "An unexpected error occurred" or (my perennial favorite) "Object reference not set to an instance of an object?" Like me, you probably scratch your head when you see error messages like those.

Writing error messages isn't as simple as it sounds, though. I'd like to share a technique that I've used and refined over the years to write effective error messages.

Elements of a good error message

An error message should be meaningful. By that, I mean full of meaning not only for a developer, but also for the user of the software. To prevent any panic or confusion, the message should be clear.

An error message should be meaningful.
A meaningful error message should:

  • be short (you can write in sentence fragments);
  • contain a description, in plain language, of what went wrong; and
  • use wording or a tone that doesn't (whether explicitly or not) blame the user.

The message can also contain an error code or the location of a log or error file that the user can send to support. You can also include a link that points to the documentation or any troubleshooting information.

Let's say you're writing an error message for a failure to print a document. The message "Printing failed" isn't as meaningful as it could be. Instead, that error message could read:

  • "I couldn't print your document. Check your printer or connection."
  • "Printing failed. Please check your printer."
  • "Couldn't print your file. Check your printer or refer to troubleshooting documentation."
  • "The file didn't print. Is your printer turned on?"

Creating effective error messages

I've taught my technique for writing better error messages to colleagues, and they've found it to be useful. I think you will, too.

If you need to rewrite an existing error message, write the current text on a sticky note and slap it on the top-right corner of your monitor. Or, if you're writing a new message, talk to a developer or quality assurance person to get the details of what the error is about. Write the key points on a sticky note and slap that on your monitor. Either way, the sticky note is there as a prompt.

Next, fire up a text editor or grab a pen and paper and start writing. The goal is to let ideas and words flow out of your brain. Don't worry about whether what you're writing is any good. Why? Most of what comes out isn't going to be great. Most of it will be unusable. You can eliminate the chaff later. Try to come up with between four and 10 variations for the message; the more the better.

Always write error messages in a conversational tone, but don't get too cute or jokey.
Always write error messages in a conversational tone, but don't get too cute or jokey. Although an error message like "Oops! Something went wrong between your printer and me. Better check to see if everything is OK" is easy to read, it's too long and doesn't get to the point quickly enough.

Trim, trim, trim

Once you have your list, whittle it down to between two and five possibilities. Then, send those possibilities to your team. This often results in a consensus in favor of one bit of text. Often, but not always. If that consensus doesn't come, try mashing up a couple of the most popular choices to get an acceptable alternative.

The key to using this technique is to not get hung up on the quality of all your ideas. You just need to let the words flow, and then edit and tweak the final error message until it's good enough to use.

About the author

That idiot Scott Nesbitt ...
Scott Nesbitt - I'm a long-time user of free/open source software, and write various things for both fun and profit. I don't take myself too seriously and I do all of my own stunts. You can find me at these fine establishments on the web: Twitter, Mastodon, GitLab, and...