Include error messages?

Subject: Include error messages?
From: "Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 30 Jul 2002 16:29:12 -0400

Rhina Bilbao wondered: a product manager wants me to include a list of
screenshots of all the possible error messages a user might encounter using
our software with a short (2-3 sentence) description of what it means
because the product has no Help (yes, i know!) included with this first
release. And she wants it done in a text file that will be included on the

Well, unless you're a wizard of an ASCII artist, you're going to have
trouble getting those screenshots into a text file. <g> Graphics aren't very
useful in this sense unless the error messages are all very visually
distinct (e.g, some red, some blue, some round, some square). It's the
message text you want to focus on.

The basic idea is great, but there's no reason to limit yourself to text. If
you're working on software for any reasonably modern operating system, why
not turn these error messages into an HTML document? That lets you group
error messages into categories (e.g., there may be 15 printing errors, 20
saving errors, etc.): start the file with hyperlinks to each of these
subject areas, then alphabetically list the specific errors under each
message. Better still, use headings and subheading, such as:

Printing errors
- Unable to find printer because
Software is nasty, that's all
You shouldn't own a computer
- You can't imagine how
Creatively we can generate errors
Imagination-challenged you are

The first of these messages, read in full, might be "Printing error: Unable
to find printer because software is nasty, that's all". Note that I've cut
out the redundant text using indenting because otherwise, skimming 15
message that all begin "Printing error: Unable to find printer because..."
is an exercise in frustration.

You may not be able to produce HTML for various reasons, but the same basic
approach works wonders even in a text file.

--Geoff Hart, geoff-h -at- mtl -dot- feric -dot- ca
Forest Engineering Research Institute of Canada
580 boul. St-Jean
Pointe-Claire, Que., H9R 3J9 Canada
"User's advocate" online monthly at
"The skill of writing is to create a context in which other people can
think."--Edwin Schlossberg, designer (1945- )

Your monthly sponsorship message here reaches more than
5000 technical writers, providing 2,500,000+ monthly impressions.
Contact Eric (ejray -at- raycomm -dot- com) for details and availability.

Buy RoboHelp Deluxe starting at only $798: you'll get RoboDemo, the hot new
software demonstration tool that's taking the Help authoring world by storm,
together with RoboHelp Office. Learn more at
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: Why do we put so many warnings in our manuals?
Next by Author: Documenting incremental releases in a What's New
Previous by Thread: Include error messages? (Was Re: Fw: Why do we put so many warnings in our manuals?)
Next by Thread: re: Include error messages?

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

Sponsored Ads