SUMMARY: Writing Error Messages (Long)

["Mason, Catheryn" <CMason -at- INFINITEC-COM -dot- com>]

Hello All:
My apologies for taking so long to post this summary. I've been busy ...
well ... writing error messages! (along with writing other screens and
taking a class in Visual Basic). A word of warning: this is a fairly long
summary, as I wanted to include the variety of responses and good advice
that I received. Thanks to all who responded; you've given me some wonderful
tips. So here goes.

My original query: "I'd like to gather advice on writing error messages that
are concise, helpful, and not intimidating to the user. I'm designing a
Windows GUI for our software and I'm finding that writing good error
messages is the hardest part of the project (for me, anyway). Anybody have
any success stories or tips to share? Anything, as a user of software
applications, that you either really like or hate to see in an error
message?"

Your responses (no attributions, sorry, and in no particular order): 

**(1) Sun's Style Guide says:
Format error messages in a way that differs from paragraph text.  Always
follow an error message with text describing why the message appears and
what a reader can do to correct the problem. If you are documenting numerous
error messages, consider compiling them into an appendix. (p. 128)

Microsoft's Manual of Style also has some good advice--use passive, third
person, do not use "you" and imply blame, give compiler strings if
appropriate (for programmers), avoid an "OK" button (no, darn it, it's not
ok that my computer blew up!) (p. 93).

**(2) My human factors mentor said to always tell the user: 
*	What went wrong
*	Why
*	How to correct it
Of course there will be necessary variants to that. The main principle he
preached was to make the user feel in control, avoid accusatory casts to
sentences, etc. I hate it when one error message is used for several
different error conditions, such that it is meaningless. If you can get
close to the developers, the logic, and the code, so much the better. 

**(3) How about putting a "help" button on your error messages? The message
itself can be short, direct, to the point. Below the message you put up to
three buttons: OK, Cancel, and Help. The Help button takes the user to a
help topic within the full help system.

**(4) If you would like to see examples of poor or even offensive error
messages, check out the Interface Hall of Shame's page on error messages at
http://www.iarchitect.com/errormsg.htm .

**(5) My own peeve is messages with exclamation points. "You must enter a
date!," etc. Another one is messages that are too cryptic to the average
user to be understood, or do not give advice on how to fix the error and
avoid it in the future. Some might say that such advice belongs in the
troubleshooting section of a help file, but I do not like hunting down the
info if I'm already upset that an application crashed or complained. I like
messages that not only tell you there's a problem, but also give you a clue
about how to fix it.  I also prefer that messages sound as non-stilted as
possible; for me, it helps to use articles and to avoid formal-sounding
terms like "ensure."

**(6) *This one caused a spin-off discussion all its own.* The worst error
message I've ever encountered is also the most common one: the dread "Abort,
retry, fail?" from DOS. This fails to meet just about all
the possible criteria for a good error message:
- it doesn't clearly explain the problem that occurred
- it uses words that are either synonymous (abort = fail?) or that are mere
placebos (I don't recall "retry" ever working)
- it provides no information on what you can do about the problem
- it provides no bug-tracking information that tech. support or the
developers can use to figure out where the problem occurred and what they
can do about fixing it in subsequent software releases.
.. snip ...
A good error message should clearly explain the problem (e.g., "there
appears to be no diskette in the A drive"), should use words that mean
something to the reader (e.g., "You have two options: Cancel or Try again"),
should explain what to do about the problem (e.g., "Insert a diskette and
click the button labeled Try again"), and should provide a clue to the
support staff (e.g., at the bottom of the dialog box, "Error code = Disk
error 27"). The latter is moderately more work for the developers, since
they actually have to think about tracking errors rather than just using a
one-size-fits-all error message for every possible error (e.g., "an error
occurred... try again"), but it's not rocket science and it's not all that
time-consuming. It has the offsetting advantage that the support staff can
look up the error code in a tracking database to determine how frequent the
problem is (thus, how important it is to fix) and what the most common
workable solutions have been.

Minimalism does not mean writing as little text as grammatically possible;
it means providing all the information that the user needs to understand
what's going on and respond, and nothing more than that. Minimalist
information should also be concise, but not at the expense of becoming terse
or telegraphic. Second, there's a misconception that providing additional
detail is necessarily verbose. As in all other forms of techwhirling, you
can provide a concise message at the top of the dialog box, followed by a
blank line, followed by elaboration for those who need it; those who don't
will simply read the first line and proceed on their own. An interesting
compromise (which I've seen here and there) is a "More info." button; the
error message itself is reasonably concise, and those who want or need more
information can click the button to get details.

**(7) First off, I believe these messages should be called screen messages,
instead of telling the user he or she MADE A MISTAKE. That alone makes a
difference. I am of the opinion that most (at least three-quarters) of
"error" messages are really not errors in the first place. They are just
inserting the wrong value in a field, or something to that effect. Telling
the users they made a mistake doesn't help at all. The purpose of a message
is (or should be) to HELP THE USER PERFORM A TASK. Anything in the message
that strays from this objective is either extraneous or, worse, damageable.
Any message that just says "you've made a mistake", in whatever terms,
serves no purpose other than aggravate the user. A message should do the
following:
1. Explain in simple, succinct terms what the problem is, WITHOUT BLAMING
THE USER for having done anything.
2. Tell the user how to FIX the above problem, or at least how to TRY to fix
the problem. If there are several things that the user can try, ALL these
options should be given. If needed, you can use the "More info..." button.
Therefore, I suggest you, as a technical writer, argue with programmers
about the wording of messages. Actually, what you should do is try to
"reproduce" each and every message in a list of messages. If there is any
message you cannot reproduce, ask questions, probe, argue.

**(8) I like to provide two levels of usage.  In essence, this entails
setting variables (for novice or pro), and giving users the option of
switching to the pro level.  That way, novices received hand-holding
messages and directions, while pros were told only what they needed to know.
That way, they could zip ahead rather than having the system spoon-fed to
them -- while the novices received all the online hand-holding they needed.

**(9) It can be fairly easy to provide guidelines for writing useful error
messages. But then I noticed that you're designing the GUI, and so I say, in
a nutshell, do the design so that users can't make errors. 

To address the actual authoring of error messages, instead of veering from
minimalist to too much, do both. That is, layer the information. Provide
users with enough information to tell them what happened and how to resolve
it, then provide a way to get more information if needed or wanted. The
information that goes in both places depends, of course, on your audience.

However, a better goal is to design, as much as possible, the interface so
users can't make errors, or at least will have a more difficult time making
errors. This can be done in many ways, including labeling, but the entirety
of methodology is too much for a simple list posting. You can also use
pop-up windows, as described on page 250 in the book "Microsoft Windows User
Experience" to provide additional guidance before users take action.

Some of the things to think of in this area:
- Don't make controls available until it's reasonable. That means, for
example, if it's required that all fields in a dialog box be filled in,
disable the OK button until all the fields have valid entries (that means
programmatically doing validation as a user enters information). Or when a
document is saved, disabling the Save button and command until some change
has been made to the file. And so on.
- If procedures have to be done in sequence, consider a Wizard to lead users
through that sequence. Wizards should always be bi-directional.
- Use standard, familiar controls.
- Remember that most people scan from upper left to lower right, so consider
what users need to do and when they need to do it when designing windows and
dialog boxes.
- Design based on user goals, not software function.

The last point is by far the most critical.  For more information, read Alan
Cooper's "About Face."

**(10) I wish people would stop making users feel like THEY are at the
service of the program. It is the PROGRAM that should be at the service of
the user. When I use a program, I want to feel in full control of the tasks
I am trying to perform. If something goes wrong, I spontaneously BLAME THE
PROGRAM, OR THE COMPUTER, or both!! I refuse to blame myself, until I have
proof that I "absent-mindedly" entered an impossible value for a field, and
even then, I would like it to be "impossible" to make such a mistake. For
example, a beep that sounds as soon as I move on to the next field, and a
message reminding me that the value is impossible. I DON'T MIND THESE
MESSAGES, because very quickly, I will learn to enter appropriate values. It
is the OTHER messages that drive me crazy.

More info:
- look up the any OS style guidelines (Apple, Windows, Motif, ...).
  They give similar advice and it's all pretty sound.
- I like Julianne Chatelaine's piece 'Polite, Personable Error
  Messages', available from the STC Usability SIG archives at:
  http://stc.org/pics/usability/newsletter/newsletter-archives.html

That's it folks! If I excluded anyone's points from this summary, it was
inadvertent and I offer my apologies. Again, thanks to all. 

Catheryn Mason, Technical Writer
Infinitec Communications
cmason -at- infinitec-com -dot- com
Winner, 1999 IABC Bronze Quill Award of Excellence for Technical Writing