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.
> >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 technical...at 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.
__________________________________________________
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.
