Seeking advice on the best way to phrase an error message?

Subject: Seeking advice on the best way to phrase an error message?
From: Geoff Hart <ghart -at- videotron -dot- ca>
To: TECHWR-L <techwr-l -at- lists -dot- techwr-l -dot- com>, Tracy Taylor <ipsque -at- yahoo -dot- com>
Date: Fri, 30 Mar 2007 09:18:34 -0400

Tracy Taylor wondered: <<I'm trying to find the best way to phrase a
specific error message in a common situation. Basically, the
application has a form that the user needs to enter, and let's say he
or she leaves a field empty - in this case, it's Phone Number.>>

Nothing works quite so well as getting to the point, politely,
without pointing the finger at anyone -- and as you note, clearly
explaining what the reader must do to solve the problem. "Please add
your phone number [format description] in the highlighted field." No
need to preface this by saying the phone number is missing. You
wouldn't be asking me to enter one if you thought one was present!

The "format description" should not be required, but I frequently see
fields with no affordances telling me whether brackets and a hyphen
are necessary -- or not -- then piss me right off by asking for a
"valid" number without specifying what "valid" means. I usually get
it after trying the two or three primary possibilities, but why make
me go through this process? And you can never overuse "please".
(Well, you can if you're sufficiently creative. <g>)

Good design would group the information under two headings: "Required
information" and "Optional information". Forget about those stupid
asterisks. If you've got to waste a line on the display anyway by
explaining this in a footnote, you're better off building that
footnote into the design and turning it into headings.

Also note that highlighting incorrect or missing information in red,
which seems to have become some sort of Web-wide default, is a poor
choice. Something like 5% of your audience (mostly male) won't be
able to distinguish this highlighting from the background without
painful squinting. Even those who can clearly see the color still
have to scan through all the other information in an (often long)
form to spot it. Why not present a new form containing only the
fields that need to be redone? A bit more programming, but really not
rocket science: if you can identify the field that contains the
error, you can certainly redisplay only that field.

<<Current error message in the app I'm working in is: "Phone Number
is required and must have a value." It's not the worst way to say
it, especially for a system generated error message, but I'm
wondering if there is a better way.>>

As noted above, "must have a value" isn't helpful. "I'm not stupid. I
know you asked for my phone number. What value do you want? I thought
I typed it correctly the first twelve times, but clearly your idea of
valid ain't mine!"

<<Here's what Amazon said in a similar situation: "Important Messages
There is a slight problem with your order. (See below.) You didn't
enter a phone number. Please enter your full phone number below.">>

I'd call this a "not quite worst practice, but not really anything
close to a best practice". <g> Of course it's an important message.
Why would you be making me read it if it weren't important? A slight
problem? Well then process me bloody order already. Don't bother me
until you find a serious problem. [Thus: eliminate both parts. I'm
overly fond of adjectives and adverbs in my own writing, but unless
they're crucial to the meaning, they have little or no place in
technical writing.]

-- Geoff Hart
ghart -at- videotron -dot- ca / geoffhart -at- mac -dot- com
Coming soon: _Effective onscreen editing_ (


Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include single source authoring, team authoring,
Web-based technology, and PDF output.

Now shipping: Help &amp; Manual 4 with RoboHelp(r) import! New editor,
full Unicode support. Create help files, web-based help and PDF in up
to 106 languages with Help &amp; Manual:

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

seeking advice on the best way to phrase an error message: From: Tracy Taylor

Previous by Author: Tools: Index palette in InDesign CS
Next by Author: Tech Writers & Educational Material?
Previous by Thread: Re: seeking advice on the best way to phrase an error message
Next by Thread: RE: seeking advice on the best way to phrase an error message

What this post helpful? Share it with friends and colleagues:

Sponsored Ads

Sponsored Ads