TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:Re: Writing error messages? (longish) From:Fabien Vais <phantoms -at- pop -dot- total -dot- net> To:TECHWR-L -at- LISTS -dot- RAYCOMM -dot- COM
I think I'll even go further than Geoff Hart on that subject. I have had
arguments about so-called "error" messages for as long as I can remember.
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
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. Like Geoff said, 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
Geoff was referring to.
I have often had arguments with programmers about error messages that did
nothing for the user, or messages that simply said to "Call your technical
support". One day, I chose a really bad message and I called the technical
support people myself, explaining that I had stumbled across this message
and it said to call technical support. I asked them what I should do about
this. THEY WERE TOTALLY UNABLE TO HELP ME. They said they had to speak to a
programmer, because this was a very rare message, and they weren't sure what
to do with it!! Can you imagine?
Therefore, I suggest you, as technical writers, 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.
Fabien Vais - Documentation Analyst (Analyste en documentation)
Technical Writing, Technical Translation/Globalization, Editing, Publishing,
Rédaction technique, Traduction/globalisation technique, Révision, Mise en
Page, Enseignement, Formation
e-mail: phantoms -at- total -dot- net
Mailing address (Adresse postale): 38 Elderidge, D.D.O. (Montreal), Quebec,
Phone/Fax: (514) 685-4752