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.
Michael Harris wonders: <<One of the most fluid issues I find in
writing technical documentation is determining when to spell out
acronyms in the first usage and when to 'assume' that since all of
the readers should have some knowledge of the material, that spelling
it out is not necessary. Does anyone have guidance in this regard?>>
When in doubt, spell it out! <g> The reason for the "define on first
use" rule of thumb is that you don't have to guess. For things that
seem awfully familiar, like PC, sometimes the answer is to use the
actual word (computer) instead. For acronym-infested documents,
always try to include a glossary. If you guess wrong, at least the
reader has a chance of figuring out what you mean.
Another important and useful rule of thumb is that if the reader
cannot be expected to understand the subject, spelling out the
acronym won't help. That leads to the question about whether you
should be using a word or expression at all: technical acronyms are
appropriate for technical audiences because they communicate clearly
and effectively, but they're meaningless to nontechies. If I tell
someone that I used real-time RT-PCR in a genetic analysis, this
won't mean anything to them unless they're a geneticist, even if I
spell out the acronym; if I expect any non-techies to be reading it,
I should simply say that I analyzed the genetic material by
increasing the quantity to a level I could detect and work with.
<<The primary customer of our documentation is a technical branch of
the Army.>>
I'm given to understand (no personal experience, but some reading--
and not fiction either) that the Army overuses acronyms, to the point
of incomprehensibility to anyone outside the service. So your client
is probably a good source of information on this: if they use the
term as part of their standard vocabulary, assume it's part of the
jargon and use it freely.
<<While CPU is well known, does it get spelled out?>>
Strictly speaking, the CPU is the chip that does the processing. Over
time the meaning has expanded to cover the box that contains the disk
drives and power supply (as distinct from the monitor), but that's
imprecise and arguably incorrect. In any event, it's probably a
distinction worth preserving if you're trying to communicate with a
technical audience. I also add this as a moral to the story: acronyms
often get used so carelessly that they stop communicating clearly.
Periodically, we should stop and ask whether we're really saying what
we think we're saying.
<<How about CORBA, which a local manager thinks is well-known enough
as Common Object Request Broker Architecture and does not need to be
spelled out.>>
That term has been around for at least a decade, and the only people
who should ever be forced to see it in print or online are people who
already know what it means.
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
