Panasonic Youth rob sanheim writes about software, business, ruby, music, stuff and things

How to write good error messages

An anonymous javaBlogger posted about crummy error messages in many common frameworks today. His complaint was with messages like this:

• Wrong string format
• Cannot open file
• Unable to contact server

And proprosed changing them to include the offending input:

• Wrong string format in state code: “WI_1234″
• Cannot open file: my.settings
• Unable to contact server: your.mom.com

I would say go even further. Explain exactly why the input failed and what input is expected. For example:

• Wrong string format in state code: “WI_1234″ — state codes must be in the format of: “AB:1234″ and are case sensitive.
• Cannot open file: my.settings — the file was not found, make sure its in /path/to/resources/.
• Unable to contact server: your.mom.com - returned error code 500 — ensure that the server can respond to HTTP requests on port 8080

Put your self in the role of the user who is just starting out with your framework. And by “user” it could be a programmer extending your framework, a teammate using your interface, or Joe User trying to use your GreaseMonkey script. Imagine what would be helpful for someone who knows absolutely nothing about the inner workings of your program, and what sort of information would be helpful when things go wrong. Graham wrote “Empathy is probably the single most important difference between a good hacker and a great one.” So have some empathy, and spend a little more time on those error messages.

Yep, we have a lot to learn from usability guidelines here

http://www.klariti.com/technical-writing/writing-error-messages.shtml

Tell the user what happened, explain the consequences if it’s not obvious, outline how to fix it, explain what to do if they can’t fix it.

(In verbose mode at least)

Good to see that you agree. Your solution is even better. My blogpost was a result of spending days looking trough websites only to find that the solution was something that could easily have been summed up in a one line error message.