Error messages - summary

[Max Zimani <max -at- HERMES -dot- SI>]

Fellow whirlers,

Thank you for responding to my request for information on error
messages. Following is a list of your (four) responses.

Max

-----Original Message-----
From: Max Zimani <max -at- HERMES -dot- SI>
To: TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU <TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU>
Date: Friday, February 13, 1998 3:08 AM
Subject: Error messages


>I work at a software producing company as a technical communicator. I
>was assigned the task of writing online error messages for our manuals.
>Could anyone recommend an article on the basics of writing error
>messages. Thank you in advance.

Max

1.
Joe Sokohl wrote:

Recommend you look at
     http://www.iarchitect.com/hterror.htm
     This link provides good tips on what to do.

     and also

     http://www.iarchitect.com/errormsg.htm
     This link shows what NOT to do.
     HTH,

     joe
     Joe Sokohl
     jsokohl -at- campbellsoft -dot- com

2.
Kris Olberg wrote:

At the very least, the error message must PROVIDE MEANINGFUL INFORMATION
TO
THE USER such as how to recover, where a recovery file was written, who
to
call, what to do, etc. If no action is required, the message should say
that.

Put yourself in the place of the user and ask, "If I got that message,
what
would I think/do?"

Regards...Kris
------------------------------
kolberg -at- actamed -dot- com
kris -at- olberg -dot- com

3.
Sam Alper wrote:

I've never actually seen an article on it, but the general rules I
follow
are:

Tell the user what is probably wrong, not what the internal flag is.
If there's space, tell the user how to correct it.
If at all possible, see if you can convince the programmer to have the
  software correct it for the user.

Sometimes telling the user what is probably wrong can be misleading.
For example,
we use ClearCase and one of its error messages is "Page Fault."  What
that usually
means is someone has updated the view's code line since you started and
the page
that is in memory now has obsolete pointers.  However, our software is
still in
development and it could also mean there was a problem with the program
and it
produced a page fault.

It is also good to tell the user how to correct the problem, if you can.
One
message that I documented for logic analyzers is
"Slow or Missing Clock"
This means that the logic analyzer didn't see the clock activity that
the user
told it to look for.  This can be caused by an incorrect clock
specification
(the user used clock J when it should have been K), capacitive load on
the target
system rendering the clock signal too weak, or a bad connection.  It
could even
be that the user's target has a very bursty clock that is mostly
inactive.
Clearly, there isn't space in the error message field to tell them all
this, so we
have a help button for more information.  (Well, we do now; older models
had a book.)

Last example, one message we convinced the programmers to code around is
"Time Tags Must Be On to Correlate Measurements."  The customers only
got this
if they tried to compare or display together two measurements, and the
state
measurement(s) didn't have time data.  We knew *exactly* why it came up,
there
were no alternate causes, and the correction was a hard-to-find option
field in
a totally different menu than they were in.  So, the newer models now
change the
time tags, pop up a message saying time tags are now on, and instructing
the user
to make the measurement again.  The best error message is a non-existant
error
message. :-)

Hope these examples help.

Sam Alper
salper -at- col -dot- hp -dot- com                  "Not HP's opinions, and all that"

4.
Jon Leer wrote:

I don't have an article to suggest. However, I thought I would pass
along
what I did a few years ago. The engineers inevitably have a text file
containing all of the current error messages they use for debugging.
With
their help, we organized them by function. I cleaned up the language and
made them less cryptic for an end-user target market.

Unfortunately, these were simply added as an appendix to the hardcopy
documentation. However, they could have been hooked into online help.

Jon Leer