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.
Thank you for responding to my request for information on error
messages. Following is a list of your (four) responses.
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.
jsokohl -at- campbellsoft -dot- com
Kris Olberg wrote:
At the very least, the error message must PROVIDE MEANINGFUL INFORMATION
THE USER such as how to recover, where a recovery file was written, who
call, what to do, etc. If no action is required, the message should say
Put yourself in the place of the user and ask, "If I got that message,
would I think/do?"
kolberg -at- actamed -dot- com
kris -at- olberg -dot- com
Sam Alper wrote:
I've never actually seen an article on it, but the general rules I
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.
we use ClearCase and one of its error messages is "Page Fault." What
means is someone has updated the view's code line since you started and
that is in memory now has obsolete pointers. However, our software is
development and it could also mean there was a problem with the program
produced a page fault.
It is also good to tell the user how to correct the problem, if you can.
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
told it to look for. This can be caused by an incorrect clock
(the user used clock J when it should have been K), capacitive load on
system rendering the clock signal too weak, or a bad connection. It
be that the user's target has a very bursty clock that is mostly
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
if they tried to compare or display together two measurements, and the
measurement(s) didn't have time data. We knew *exactly* why it came up,
were no alternate causes, and the correction was a hard-to-find option
a totally different menu than they were in. So, the newer models now
time tags, pop up a message saying time tags are now on, and instructing
to make the measurement again. The best error message is a non-existant
Hope these examples help.
salper -at- col -dot- hp -dot- com "Not HP's opinions, and all that"
Jon Leer wrote:
I don't have an article to suggest. However, I thought I would pass
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.
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.