Re: Error appendix

[Hal Wrobel <halwro -at- yahoo -dot- com>]

Hi Dick, and Dave, 

The only embedded errors we have are in ASP templates.
We haven't begun to try and figure out how to get
those under control. All other errors, however, are
located in separate resource files, named according to
the utility or application with which they're
associated. I have access to these files. I rewrite
the obvious in a working copy of the file and meet
with the responsible programmer to clarify the intent
of messages for which I need to know the context and
audience (programmer, administrator, end user). Where
additional information is necessary, either for how to
troubleshoot and avoid, or details to help our support
team, a "Details" button is added to the message
returned. All this information is coded into the
...err.h files. For Java where you don't have separate
header files, you'd need to work with the source, as
Dick does. 

This system often leads to some clean-up in the code
and a lot of elimination of unnecessary or obsolete
messages, which can be very important if your company
translates into a number of languages. 

Beyond that, what with space being limited in error
messages, if too much explanation is required, the
issue is probably something that should be fixed, and
possibly put in a release note until the next version
where it can either be properly documented or ignored.

Hal   

Dick Margulis  wrote: 

I've done this, but it does not make for a
user-friendly document. As a first pass at improving
the situation, I asked a friendly developer to create
a printout that showed all embedded error messages and
the source file/line number where they appeared in the
code. I then redlines the printout, and a developer
spent a couple of hours updating them all. Now that we
have a fully fleshed out development organization, the
error messages are negotiated during the design phase,
with the designer, programmer, and tech writer all
able to review the design before the programmer
implements it. This ensures that for the most part a
tech writer has at least laid eyes on every error
message and had the opportunity to clarify it.DickDave


Stewart wrote:

> For the software I currently document, the engineers
have written a 
> large number of error messages that appear when a
user performs a task 
> incorrectly.
>
> For instance, an error message will pop up on the
screen when a user 
> neglects to import a required file or types a number
that is outside 
> the minimum and maxiumum allowed values for a
certain parameter.
>
> We've received feedback from customers that the
error messages are not 
> descriptive enough, and we're working on making the
messages more 
> comprehensible so users know exactly what went wrong
and how to fix 
> the problem.
>
> I'm wondering if anyone has ever included an
appendix in their 
> documentation listing each error message in the
source code, along 
> with more extensive descriptions of the solutions to
each problem?


__________________________________________________
Do You Yahoo!?
Send FREE video emails in Yahoo! Mail!
http://promo.yahoo.com/videomail/

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Attention ForeHelp and Doc-to-Help Users! Upgrade your existing product to
RoboHelp for only $299, through January 31st. RoboHelp can import your
existing Help projects! Learn how else RoboHelp can benefit you. www.ehelp.com/techwr

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit 
http://www.raycomm.com/techwhirl/ for more resources and info.