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.
Our opinion is that - if the message pops up there should be a documented
procedure to handle the situation. Sometimes these situations can be quite
involved, but that's what you get when you're writing for the common market.
Each error message starts with a module code. XXX and then a sequential
number 999. (XXX-999).
We try to make our messages user-friendly, easy to read and understand; but
they are documented because we are planning for the worst-case scenario,
which is: A new user (who does not know where screens are, how to get to
them or even what they may contain) is most likely to do very silly things
that will confuse our product.
The product tries to recover when it can, but sometimes - either by the
logic under which it was created, constraints based on the operating system
or the we-didn't-think-of-that fudge, it can't recover. That's when we pop
an error message asking the user to do something.
So I document them using the following format:
Error Number:
Error Message: (this is identical to what appears on screen)
Error Level: (One of five types, describing the seriousness of the
situation)
Condition: When this should occur
Proposed Solution(s): What the user should do about it. There may be more
than 1.
One of the main reasons we've gone with this is a built-in length
limitation. Without this type of documentation, we found our error messages
just wouldn't fit nicely in a pop-up window.
Originally just a few messages had to be documented, but over time we've
found it to be a very handy reference for Technical Support and Quality
Assurance as well as users.
Simple errors are: wrong format/content in the dialog types. Complex ones
deal with corrupted files and/or registry entries -- requiring the user to
jump through a few hoops to reconfigure the software.
Yes it's big.
But - if you're worried about it you could always make it a separate online
help (or PDF) file; and refer to it in your main guide. Treat it as
supplementary/supportive documentation that will, at least, benefit
technical support if not the inquisitive new user.
Just my 2 cents
-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
Rebecca Downey
Senior Technical Writer
Internet Technologies Group
Matrox Electronic System
New Business Media Division
Email: rdowney -at- matrox -dot- com
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
