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

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 2

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 3

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 4

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 5

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 6

Always include suggestions to Remedy the error.