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.
> It's funny you write that because I made a complete fool of myself the first
> week of my new tech writing job when I said, "Hey, can we put a glossary in
> here?" Both of the senior writers looked at me like 1) I'd lost my mind, and
> 2) they were trying not to burst out laughing. ...
Methinks that depends heavily on audience and topic.
The larger and more complex the document, the more likely it is that you'll
need material outside the main flow of the text -- table of contents, index,
glossary, bibliography, web links, cross-references, footnotes or text
boxes with extra explanations, ...
I would expect any professionally-done documentation set for a complex
product to include most of those. I don't see how several hundred pages
of documention could be possibly usable without at least TOC, index,
some cross-references and a glossary of at least the acronyms used.
The shorter and more task-focused your document is, the more you want to
keep it to one smooth text flow, and the less you want anything outside
that flow. I think you still need cross-references in most cases, though.
It also depends on medium. The same chunk of information, that doesn't fit
in the main flow but is needed for some readers, might be:
a footnote in an academic paper
a side text box in a printed manual
a hyperlinked glossary entry in a web version.
Whether you just explain terms as you go along or move those explanations
out of the flow also depends on how you expect the material to be read.
If reading is linear, explaining once when the term is introduced works,
but for a reference document that can get opened anywhere, it doesn't.
You have to either explain the term in every section it shows up in or
move the explanations out to a glossary, or to an introductory section.
(quoting someone else...)
> It's hard
> enough to get users to read a manual, much less the glossary of a
> manual--especially if the user's in the middle of a task and they're
> looking for help. Their reaction to an unfamiliar term like "radio
> button" won't be "I'd better brush up on my terminology; where's the
> glossary..."--it'll be "Why can't they write this #$^&* thing in
> English!"
Sometimes it's "Why doesn't this jerk define his/her terms?"
I think part of this depends on your range of users. For example, I write
mainly for system administrators who almost certainly understand terms
like "boot" or "ethernet", so I use those freely with no effort to define
or explain them. For another audience, you'd need to define or explain
them.
Mostly, it is not that clear cut. We have the same problem teachers do.
Our audience is by no means uniform, and we have to try to provide
something for everyone.
For example, my readers can be anything from novice system admins to
well-known net.wizards. Some may be expert in one area, but novices
in another. So early in my docs (www.freeswan.org) I have recently
added this section:
(using // to mark the hyperlinks)
|Throughout this documentation, I write as if the reader had at least
|a general familiarity with Linux, with Internet Protocol networking,
|and with the basic ideas of system and network security. Of course
|that will certainly not be true for all readers, and quite likely
|not even for a majority.
|
|However, I must limit amount of detail on these topics in the main text.
|If I tried to explain everything here, the result would be completely
|unreadable.
|
|If one or more of those areas is unknown territory for you, there
|are plenty of other resources you could look at:
|
|Linux
| the /Linux Documentation Project/ or a local /Linux User Group/ and
| these /links/
|IP networks
| Rusty Russell's /Networking Concepts HowTo/ and these /links/
|security
| Schneier's book /Secrets and Lies/ and these /links/
|
|Also, I do make an effort to provide some background material in
|these documents. Explanations that do not fit in the main text, or
|that not everyone will need, are often in the /glossary/, which is
|the largest single file in this document set. All files are heavily
|sprinkled with links to each other and to the glossary. If some
|passage makes no sense to you, try the links.
|
|For other reference material, see the /bibliography/ and our
|collection of /web links/.
|
|Of course, no doubt I get this (and other things) wrong sometimes.
|Feedback via the /mailing lists/ is welcome.
Whirler comments are also welcome.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Announcing new options for IPCC 01, October 24-27 in Santa Fe,
New Mexico: attend the entire event or select a single day.
For details and online registration, visit http://ieeepcs.org/2001
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.
---
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.
