How does one write good error messages?

Question

• Apologise.
• Say what went wrong.
• Say how to resolve it.
• Be polite.
• The message should be worded so that the application accepts responsibility for the problem. Never blame or criticize the user or make them think it's their fault.

Example:
"Sorry, the file could not be opened. Please check that the file is not already opened by another program and try again."

If there are additional details that would scare the user such as an error number or something else only a developer would understand, don't show them. Write them to a log file, or have a details button that can be pressed to get to them.

I'm assuming you're talking about showing error messages to users in message boxes or on screen.

Do you mean user-facing or in a log file for admin/dev staff?

I think these are important, in general:

• Time-stamp
• Severity level
• what went wrong
• Answer the questions "do I need to take action?" and "if so, what action?"
• dev-level detail (not prominently, if user-facing)
• consistent format and terms

I think all of these are important, but the prominence will change depending on the audience (as dmckee points out). Another tip (in general) is to answer the 5 W's (who, what, ... etc)

For end users: Tell the user what to do. Should the user change some input value, retry in 5 minutes or call support?

I work at a software security firm, so my answer may be significantly different from some of the above answers.

A good user facing error message is:

Balanced between being generic and specific - You want to give the user enough information that they can correct their error and move on, but keep in mind that an attacker could use these same error messages to attack your site. A good example of this is a login control in which an error message is returned “incorrect password for user joe” or “user joe does not exist in this system” this tells the attacker that they are on the path of discovering correct users. Which when you have neither a username or a password is half the battle.

Tells the user what went wrong – again this is balanced between generic and specific. A user never needs to see an ODBC error message, but it might be helpful for them to know that the error was your fault and that they should try again in a few minutes. Tell the user what they can do to help – if you have a backend logging system (which you should) log everything you think will be useful, then generate an ID that you can provide to the user so they can call or e-mail you and tell you exact repro steps. You could also automate this by exposing an bug submission form when an error happens.

Be consistent – use an error lookup table to ensure that all your errors are the same (for the same problem) and that they are well written. Typos, spelling mistakes and grammatical errors cannot be tolerated in production software.

A good error message has three parts:

1. The problem - explains that an error has happened;
2. The cause - explains what caused the problem;
3. The solution - explains how to overcome the problem.

If you are writing or reviewing your error message, first focus on getting these three points written. Even if the message is awfully long, don’t worry about that when first writing. You can always go back and simplify it later.

But the opposite is not true. It’s difficult to shape a small message into one that clearly explains the problem, cause, and solution to the problem. You will be constantly editing your thoughts to ensure the message stays small, and at some point you will become blocked. Yes, I've experienced that problem several times, so I know how hard it feels.

After you ensure your message contains all these three parts, its time to review it. You need to edit it to ensure it:

1. Is user centred - avoid jargon and words your audience will have an hard time understanding;
2. Is direct - as William Strunk said, “Put statements in positive form. Avoid tame, colourless, hesitating and non-committal language”;
3. Omits needless words - cut, cut, cut.

As you can see, this framework is simple and does not need much thought.

Sources:

• http://www.joaofn.com/post/how-to-write-error-messages/
• http://blogs.msdn.com/b/brada/archive/2004/01/28/64255.aspx
• http://msdn.microsoft.com/en-us/library/dn742471.aspx