Writing clear error messages

Error messages cause our users frustration –and cost us localization dollars to boot. When a user sees the message they’re already frustrated.

Error messages cause our users frustration –and cost us localization dollars to boot. When a user sees the message they’re already frustrated. Whatever they were trying to do didn’t work. Now they see a (sometimes) ambiguous message that isn’t helping:

• Internal error {1}
• Array index exception

What’s our style?

The style for Avocent®/LANDesk error messages is:

State the problem. Offer a solution.

I know sometimes I’ve asked the engineers why we’d get to this error in the first place and they don’t know. Sometimes it’s because it’s a relic message; sometimes it’s because we have too many error cases referencing the same message. (In that case we should break it up into more discrete messages.)

All error messages should contain 2 parts:

State the problem. Offer a solution.

This gets the user back on track without leaving them confused about what just happened. So if they’ve typed alphabetic characters in a field expecting numeric characters only, tell them that. This beats just telling them: WRONG! and leaving them to figure it out.

In its basic form, this means: “Invalid value. Type a new value using numeric characters only.”

Tips

Error messages should:

1. Be written in the user’s language and should be easy to understand.
2. Be informative but concise. They do not need to include the word “please”.
3. Be consistent in look and behavior.
4. Validate all errors on a screen at once. Users should not have to fix a problem, re-select Save or Submit, then receive more error messages.
5. Be displayed in context when possible, especially in the case of missing or incorrect data in forms. Keeping the user in context helps them fix the problem more quickly.
6. Not make the user feel stupid or accuse or blame the user. (They’re the ones paying us the money after all.)

What should I look out for?

Spelling and grammar problems

It’s fairly common to see spelling errors, punctuation errors, and style errors such as:

• Can not for cannot
• Ocured for occurred
• Email or E-mail for e-mail
• web for Web
• username for user name
• login for log in (the verb)

These are all things that make us look less-than-professional. Grammatically incorrect sentences make it difficult for everyone to read (and localize). If you need a spell check, copy the string into Word and spell check it there before checking it into the string file in Dev Studio.

Confusing sentences

Some of our technical jargon looks like mush—providing some context can show a localizer it’s not just a string of random words:

“The select statement must contain a where clause.”

to

“The SQL select statement must contain a where clause.”

Unhelpful messages

Sometimes it seems we feel compelled to write short fragments for error messages—even when they are going to pop up into their own message box and there is no real size constraint:

“Invalid character.”

Ok. So I just filled out a dialog box with 5 text boxes and that’s all I get? Tell the user what happened and how to fix it:

“The specified user doesn’t exist. Type a new user name containing only alphanumeric characters.”