How to write better error messages

Try this simple technique to write messages that help users understand the reason for errors.
406 readers like this.
A cat under a keyboard.

Opensource.com

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.

That idiot 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 all that seriously and I do all of my own stunts.

8 Comments

Sounds like Microsoft messages. Polite, but you still don't have a clue (as both a user and developer) what's going on. Can't you open a print device? Doesn't it accept data? Was communication broken with a daemon or a pipe? As a developer you highly depend on what a call returns - and sometimes that's a big, black box that just says "I won't". I think a good error message gives the cause and the way to fix it. If that isn't possible, at least give the developer a clue what's going on. In some cases I'd rather see "Pipe closed unexpectedly on printer daemon" or "Can't write to /dev/lp0" than message that is utterly useless to us both.

There should be two levels of error messages for most errors.
First level, as described here, with simple suggestions how to correct, if possible.
Second level contains, or explains howto collect, debugging information to relay to tech support. This level is mostly for software errors.
Unfortunately, software errors are not predictable (or should not be, code should handle the obvious, predictable errors).
Too many developers play hideAndSeek, not wanting to be contacted for "piddly" errors. There should not be "piddly" errors in code.
If the condition is correctable, instruct the user how to correct it. If the condition is not correctable by the user, it should be correctable by you.

Although I don't know where and what to fix, the error messages from Python are pretty cryptic.
One thing I don't like, though, is anthropomorphising messages, like your example "I couldn't print your document. Check your printer or connection." Who's this "I" that's sending this message?

Pretty good advice for standalone programs.

But: never ever give detailed error messages and more importantly do not show any system names and version numbers etc. when programming a online web system.

Doing that would be a hackers heaven.

My favorite error message is one that I encountered over 40 years ago on a real-time process control computer at an oil refinery in Ohio. No matter what went wrong the computer would always stop and it had only one error message - "CURSE YOU RED BARON." Not even a little helpful.

I really hate the recent trend towards overly conversational messages and using personal pronouns for inanimate objects. I don't want to read "Hang on, I'm just setting a few things up for you" when good old "Please wait" would have done fine.

Your criteria for an error message are totally wrong.

"Printing failed" is a terrible message.
"Printing failed. Please check your printer" is just a longer version of the same message. It doesn't even meet your rules about being short or saying what went wrong. Instead, it was longer, and displayed what didn't happen rather than what went wrong.

An error message should say:
* What happened -- not what didn't happen!
* The subject of the action
* The target of the action

So "Paper Jam printing document1 to printer2" tells me what happened (paper job) the subject of the action (document1) and the target (printer2)

Error messages are never static strings. More examples:
"Unable to read file" = bad
"Insufficient access rights reading foo.txt" = good

The source of this problem is from programmers not following best practices. Often I see code like this:

result = printer2.Print(document1);
if result != success then display "Static error message that tells me nothing"

This code should not pass a code review. The second line should be:
if result != success then display "{result} when printing {document1.Name} to {printer2.Name}"

Every operating system made in the last 25 years tells the program what went wrong. But programmers continue to discard that information. In modern languages with exceptions, the coder doesn't even have to write code to handle the error. It's generally just a top-level error handler that displays the exception to the user.

Context matters.

Bad: Could not delete file.
Good: Could not delete file foo.txt
Even better in client applications (but not web applications): Could not delete file C:\MyDirectory\foo.txt.

Bottom line: Not only mention what did go wrong, but also what objects are of user-relevance in this transaction.

Creative Commons LicenseThis work is licensed under a Creative Commons Attribution-Share Alike 4.0 International License.