Re: Error messages - summary

Subject: Re: Error messages - summary
From: "Martin, Chuck" <chuckm -at- EVOLVESOFTWARE -dot- COM>
Date: Thu, 19 Feb 1998 10:17:36 -0800

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.

Now, I can't take credit for this philosophy, I can only echo and
support it. To see what error message *really* communicate to users, see
http://www.cooper.com/manifesto/manifesto.html#top.

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




Previous by Author: Re: Headhunters in the Bay Area (Specific Information)
Next by Author: Re: Non-existent "features"
Previous by Thread: Re: Error messages - summary
Next by Thread: Frame 4 book PDF help needed please


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


Sponsored Ads