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.
While the advice for writing error messages is good, I'd like to note
that error messages are a sign of failure on the programmers' part. The
software should be designed so users can't do anything that would need
an error message.
But I'd guess that if you're at the error-message-writing stage, the
software design is pretty well set. Push for better in the next version.
On Thursday, February 19, 1998 12:06 AM, Max Zimani [SMTP:max -at- HERMES -dot- SI]
wrote:
> 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-----
>
> >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.
> 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.
>
--
"You don't look American."
"Everyone looks American, because Americans are from everywhere."
- Doonesbury
Chuck Martin, Technical Writer
Evolve Software | Personal
chuckm -at- evolvesoftware -dot- com | writer -at- best -dot- com
www.evolvesoftware.com | www.writeforyou.com
