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: A very detailed glossary From:Bruce Ashley <bashley -at- CREATEPRINT -dot- COM -dot- AU> Date:Wed, 14 Oct 1998 12:25:03 +1000
I'd go a step further and totally remove the detail from the manual. As you
say, a glossary is a short explanation of the terms therein.
If lengthy detail needs documenting, then it should be placed in a Terms
and References Guide or such. The glossary can then point to this document
as needed.
Personally, I'd be more worried about the person who told me to include
such a glossary. I'd try to get him/her out of the loop ASAP.
Life's tough enough.
Regards,
Bruce Ashley
OZ
Q: You wrote, asking for suggestions about:
"I started out writing a glossary for one of our manuals. The glossary
consisted of about twenty-five terms and their definitions. As the
review process went on, I've been asked to add a more detailed
explanation of how each is used and an example for each term. I've
now ended up with about one to one-and-a-half pages of text for each
term. Is this still a glossary?"
A: "Glossary, n., a list with explanations of ... technical terms; a
partial dictionary" (Shorter Oxford English Dictionary, 1984) and as there
is no stated limit to the size of the said explanations, what you have
written is "still a glossary". However, my view is that more than a brief
definition takes the 'glossary' outside the normally understood meaning of
"a (partial) dictionary" and more into encyclopaedia "... A work containing
exhaustive information on some ... branch of knowledge, arranged
systematically." (ibid).
Suggestion: How about putting a succinct definition in the glossary, along
with a reference back into the body of the document where the more detailed
technical material and examples, in my view, belong? In hypertext that does
not make more work for the reader, and avoids redundancy. Otherwise you
risk the glossary turning into a de-facto manual - at that, one with a
purely alphabetic structure which may not be the most convenient for its
readers.
P
