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:A very detailed glossary From:Peter Collins <peter -dot- collins -at- BIGFOOT -dot- COM> Date:Wed, 14 Oct 1998 11:34:15 +1000
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
========================================================
Peter Collins, VIVID Management Pty Ltd,
26 Bradleys Head Road, MOSMAN 2088, Australia
+61 2 9968 3308, fax +61 2 9968 3026, mobile +61 (0)18 419 571
Management Consultants and Technical Writers
email: peter -dot- collins -at- bigfoot -dot- com ICQ#: 10981283
web pages: http://www.angelfire.com/pe/pcollins/
========================================================
