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.
John Posada, responding to a previous message that I missed, wrote:
<<If the online help has a Glossary tab, I place the acronyms in there.
Lacking that, I place the acronym in the Index and link the Index
element to a topic where it is defined. Lacking that, I don't worry
about it because if the help doesn't have a Glossary or Index, the user
has bigger problems with the help than what the acronym means.>>
Both are good approaches, but sometimes a solution borrowed from the
antique world of the printed page works even better: define the acronym
the first time it's mentioned in each document, then use the acronym
thereafter. This approach ensures that the reader has at least one
chance to see a definition without having to leave their current
context (solving a problem) just to learn the language necessary to
solve the immediate problem.
In print, there's always been a rule of thumb that you can define an
acronym once per document. Though this worked fine in the pre-computer
days when people actually read for pleasure and could be expected to
read many documents from cover to cover, it works much less well
nowadays, and not at all in reference documentation (where people make
a commando raid on the docs rather than reading the entire thing). In
the new context, it's unlikely the reader would ever encounter the
definition because they dive into the midst of the documentation.
But if you pay attention to the principle behind the "rule" rather than
the rule itself, the approach still works: For each document (here, a
help topic rather than the entire help system), redefine the acronym as
soon as it appears. This redundancy takes up insignificant amounts of
space, and the payback in usability can be tremendous. Moreover, this
follows a proven approach used in encyclopedias, journals, and
symposium proceedings: where you know the reader won't read the entire
document, but will instead only read specific "articles" (the
equivalent of help topics), define the acronyms used in every
"article".
Works very well indeed--and I say this both as a past creator of such
documents and as a long-time user of them.
--Geoff Hart ghart -at- videotron -dot- ca
(try geoffhart -at- mac -dot- com if you don't get a reply)
ROBOHELP X5 - ALL NEW VERSION. Now with Word 2003 support, Content
Management, Multi-Author support, PDF and XML support and much more!
Now is the best time to buy - special end of month promos, including:
$100 mail-in rebate; Free online orientation on content management
functionality; Huge savings on support and future product releases;
PLUS Great discounts on RoboHelp training. OFFER EXPIRES April 30th!
Call 1-800-358-9370 or visit: http://www.ehelp.com/techwr-l
---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -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.
