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.
Subject:RE: Spelling out acronyms at first mention From:Deborah Snavely <dsnavely -at- aurigin -dot- com> To:'TECHWR-L' <techwr-l -at- lists -dot- raycomm -dot- com> Date:Fri, 13 Oct 2000 12:24:23 -0700
Gilda_Spitz -at- markham -dot- longview -dot- ca said:
>In the "good old days" of books only, the rule regarding acronyms used to
>be:
>
>- Spell out an acronym at first mention - for example, "see your database
>administrator (DBA)".
>- Subsequently use the acronym only - for example, "see your DBA".
>
>But when you write text for an online help system, you can't assume that
>users will read the "first" text first. So what do you with the concept of
>"first mention"?
>
>This problem is particularly tricky if you are single-sourcing, as we are.
<snip>
Mostly, what I do is twofold:
-do not acronym product names, even long-winded ones.
-make sure that ALL acronyms get into a glossary (or list of acronyms) and
build it into the online help both as a whole topic, and as a set of
individual micro-topics, one term and its definition per topic. Then when
the project nears completion (as is assembled from multiple writers if
needed), someone competent in ForeHelp use surfs through the entire help
project by searching for each term in the glossary and linking the first
instance of a term that appears in a content topic to the corresponding
definition topic as a popup hyperlink. Eh, voila!
(I've written a couple of papers about the process of single-sourcing from
FrameMaker to ForeHelp. One is published online at http://www.inframe-mag.com/archive/files/vol1/1-2/fm2fh.pdf; the other is
pending publication of InFrame's next issue but I'd be happy to e-mail the
PDF in the meanwhile.)
Best of luck,
Deborah Snavely, Document Architect, Aurigin Systems, Inc.
