Re: Error messages - summary

[Dick Gaskill <dickg -at- AG3D -dot- COM>]

Max, here are a couple of suggestions.  I didn't see your first message.

1.  Write the error messages in plain english so that end users can
understand them.  There is nothing worse than an undecipherable error
message, especially ones like the ancient DOS message "Bad command or
filename".  Your developers are very smart to have a tech writer create
the error messages.

                Use :  The virtual memory on your system is full.
                Not  :  Memory overflow

2.  Siimilar errors, even on a single product, can be generated by
different modules in the code.  Make sure each error message includes an
id number of some type so the user can find it in the manual and the
developer/engineer/programmer/support tech can easily track the cause.
Example:

                MM120  The virtual memory on your system is full.

The MM120 identifies the specific place in the code that was active when
the message was generated.  However, if possible, don't use exactly the
same text in each message, even when the errors are the same.

3.  OK, the user knows what's wrong, but now what does he do to fix the
problem?  In your manual, create a table of error messages.  For each
error message, list as many causes as are likely to happen, and at least
one action to take for each cause.

HTH

-dg



> ----------
> From:         Max Zimani[SMTP:max -at- HERMES -dot- SI]
> Reply To:     Max Zimani
> Sent:         Thursday, February 19, 1998 12:06 AM
> To:   TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU
> Subject:      Error messages - summary
>
> 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
>
> ~~
> Send commands to listserv -at- listserv -dot- okstate -dot- edu (e.g., SIGNOFF
> TECHWR-L)
> Search archives at:
> http://listserv.okstate.edu/archives/techwr-l.html,
>
>