Error Message Text - Best Practices

Question

We are changing some of the text for our old, badly written error messages. What are some resources for best practices on writing good error messages (specifically for Windows XP/Vista).

Answer 1

Always include suggestions to Remedy the error.

Answer 2

The ultimate best practice is to prevent the user from causing errors in the first place.

Don't tell users anything they don't care about; error code 5064 doesn't mean a thing to anyone. Don't tell them they did something wrong; disallow it in the first place. Don't blame them, especially not for mistakes your software made. Above all, when there is a problem, tell them how to fix it so they can move on and get some work done.

Answer 3

Try to figure out a way to write your software so it corrects the problem for them.

Answer 4

Support for multilanguage applies for all kinds of messages, but tends to be forgotten in the case of error messages.

Answer 5

I would second not telling the user useless esoteric information like numeric error codes. I would follow that up however by saying to definitely log that information for troubleshooting by more technically savvy people.

Answer 6

For any user input (strings, filenames, values, etc), always display the erroneous value with delimiters around it (quotes, brackets, etc). e.g.

The filename you entered could not be found: "somefile.txt"

This helps to show any whitespace/carriage returns that may have sneaked in and greatly reduces troubleshooting and frustration.

Answer 7

A good error message should:

• Be unobtrusive (no blue-screen or yellow-screen of death)
• Give the user direction to correct the problem (on their own if possible, or who to contact for help)
• Hide useless, esoteric programmer nonsense ( don't say, "a null reference exception occurred on line 45")
• Be descriptive without being verbose. Just enough information to tell the user what they need to know and nothing more.

One thing I've started to do is to generate a unique number that I display in the error message and write to the log file so I can find the error in the log when the user sends me a screenshot or calls and says, "I got an error. It says my reference number is 0988-7634"

Answer 8

1. Avoid identical error messages coming from different places; parametrize with file:line if possible, or use other context that lets you, the developer, uniquely identify where the error occurred.
2. Design the mechanism to allow easy localization, especially if it is a commercial product.
3. If the error messages are user-visible, make them complete, meaningful sentences that don't assume intimate knowledge of the code; remember, you're always too close to the problem -- the user is not. If possible, give the user guidance on how to proceed, who to contact, etc.
4. Every error should have a message if possible; if not, then try and make sure that all error-unwind paths eventually reach an error message that sheds light on what happened.
   
   I'm sure there will be other good answers here...

Answer 9

Shorter messages may actually be read.

The longer your error message, the less the user will read. That being said, try to refactor the code so you can eliminate exceptions if there is an obvious response. Try to only have exceptions that happen based on things beyond your user or your code's control.

The best exception message is the one you never have to display.

Answer 10

Error handling is always better than error reporting, but since you are retrofitting the error messages and not necessarily the code here's a couple of suggestions:

Users want solutions, not problems. Help them know what to do after an error, even if the message is as simple as "Please close the current window and retry your action."

I am also a big fan of centralized logging of errors. Make sure the log is both human and computer scanable. Users don't always let you know what problems they are having, especially if they can be 'worked around', so the log can help you know what things need fixed.

If you can control the error dialog easily, having a dialog which shows a nice, readable message with a 'details' button to show the error number, trace, etc. can be a big help for real-time problem solving as well.

Answer 11

For security reasons, don't provide internal system information that the user does not need.
Trivial example: when failing to login, don't tell the user if the username is wrong or the password is wrong; this will only help the attacker to brute force the system. Instead, just say "Username/Password combination is invalid" or something like that.

Answer 12

In terms of wording your error messages, I recommend referring to the following style guides for Windows applications:

• Windows Vista User Experience Guidelines, and specifically the section on error messages here.
• Microsoft Manual of Style for Technical Publications