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.
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
CD!>>
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
www.raycomm.com/techwhirl/usersadvocate.html
"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 http://www.ehelp.com/techwr-l
---
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.
