Re: Error Message Appendix

Subject: Re: Error Message Appendix
From: David Castro <thetechwriter -at- yahoo -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Wed, 16 Jan 2002 06:24:44 -0800 (PST)

> >At 3:10 PM -0800 1/15/02, Dave Stewart wrote:
> >
> >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?
> To which Scott responded:
> I think that what you initially need is for the programmers to write
> error messages that are useful to the user. In this day and age, the
> programmer should know enough that saying it is an overflow error is
> only meaningful to a programmer who is debugging the program.
> The error message should say what is wrong, and what you need to do
> to avoid this error.

I think that, probably in most cases, Scott is right. However, this isn't true
in *all* cases. I write documentation for middleware (software that sits
between an application and a mainframe database. The software has no user
interface. There is a text-based display on which we can put error messages. It
is not acceptable to users of mainframes to put extensive descriptions of how
to avoid an error message on the text display.

Therefore, we don't have an appendix for our error messages--we have a whole
manual! It's the System Messages Guide, and it has a description of all of the
error messages, listed by error number. In most, we tell them what caused it
and how to avoid it, but in some, we tell them to call tech support. We don't
have to do much to make the content less technical, because our users are
fairly least about stuff relating to the databases for which
they act as administrators.

So, there usually isn't a right solution to a problem for *all* situations.
Keep that in mind when considering how to handle providing additional
information regarding error messages.

-David Castro
email -at- davidcastro -dot- com

Do You Yahoo!?
Send FREE video emails in Yahoo! Mail!

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.

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 for more resources and info.

Previous by Author: Using work from previous employers in portfolios
Next by Author: Re: CBT Tools
Previous by Thread: Re: Error Message Appendix
Next by Thread: RE: Error Message Appendix

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

Sponsored Ads