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.
Where's the beginning? (was RE: When to Spell Out Acronyms)
Subject:Where's the beginning? (was RE: When to Spell Out Acronyms) From:Geoff Hart <ghart -at- videotron -dot- ca> To:TECHWR-L <techwr-l -at- lists -dot- techwr-l -dot- com>, mlist -at- safenet-inc -dot- com Date:Tue, 21 Nov 2006 11:25:37 -0500
Kevin wondered: <<On the issue of spelling out acronyms upon first
occurrence or in a place that readers are most likely to see 'em...
This, of course, got me to wondering what's the best approach in
Help. We've pretty much been dropping paper and PDF documents in
favor of Help. Mostly WebHelp. So, where's the beginning of Help?>>
The procedure often used in symposium proceedings, journals, and
other multi-author works may help: each paper or chapter is
considered an independent document, and acronyms are spelled out
again in each. In a Help system, that suggests doing this in each
discrete topic. Since that gets messy, particularly for short topics:
<<I _could_ spell out acronyms in hidden-til-you-click dynamic html
expanding or drop-down text... but since a person can enter Help at
any point, that would mean putting expansions behind (under? around?)
virtually every occurrence of an acronym. That would make my Help
pages even patchier than they are now. Eek!>>
One solution is to minimize your use of acronyms. That's generally
wise for a nontechnical audience in any event. A compromise solution
is to add a "Glossary" link at the top of every Help screen so that
readers can always get to the list of acronyms with a single click.
Of course, not all will see this link or use it, but it may be an
acceptable compromise.
Providing a popup definition for every acronym is an interesting
thought, since it would make the computer do the work for the user,
instead of vice versa, but that would clutter the document. You don't
necessarily want a popup for every technical term, after all, though
it might be a useful approach. Certainly, it's something I haven't
seen discussed from the perspective of the point at which you
overwhelm the user with links.
WebWorks ePublisher Pro for Word features support for every major Help
format plus PDF, HTML and more. Flexible, precise, and efficient content
delivery. Try it today! http://www.webworks.com/techwr-l
Easily create HTML or Microsoft Word content and convert to any popular Help file format or printed documentation. Learn more at http://www.DocToHelp.com/TechwrlList
