by Jean Hollis Weber
Keyword 6 (1), February 1996, p. 21. (Journal of the Australian Society for Technical Communication (NSW) Inc.)
Traps for the unwary are common in technical writing. In my 20 years of editing, I’ve seen a lot of things that have slipped by writers and reviewers.
Once I edited the glossaries for a set of 12 books for a mainframe software product. I assume from the appalling state of these glossaries that someone put them together in a hurry (possibly using some computerized tool to extract the entries from a master glossary or dictionary) and didn’t have time to edit the result.
I used one of the glossaries as a bad example for an editing class, because I thought it included every mistake I could think of.
Here’s my checklist of things to look for when editing a glossary:
- Are the entries in alphabetical order?
This sounds obvious, but some of the related questions are not so obvious. For example, how do you handle the alphabetising for: - Entries that start with a numeral or a character such as & or %
- Phrases (Does "lead time" come before or after "leading"? That is, are spaces significant?)
- Hyphenated words (similar question to the spaces in phrases)
- Capital and lower case letters (some computerized sorting systems distinguish between the two; is that what you want?)
- Are there any duplicate entries? How about entries that are almost the same and should be condensed into one?
- If large capital letters are used to separate groups of entries, are all the necessary ones there and in the correct places? Are any present that should not be there, because there are no entries that start with that letter?
- Are all cross-references (‘see’, ‘see also’ and ‘contrast with’) also in the glossary? Readers will be annoyed if they try to ‘see’ an entry that isn’t there.
- Are all the terms in the glossary actually used in the book, or in another definition? (You might have a policy of including entries that are not in the book, but are in another book in the same set. That’s your choice; but be sure that irrelevant entries haven’t crept in.)
- Are words capitalized consistently? Check especially the entries for abbreviations or acronyms, and the fully spelled-out definitions.
- If cross-references are given in a different font (for example, italics or bold), are all of them correctly done?
- Are all abbreviations and acronyms treated the same way? (In the glossaries I was editing, the abbreviation is spelled out in one entry, and a second entry defines the spelled-out term. The spelled-out entry has the abbreviation in parentheses after the term. There are other correct ways of doing this; just be sure your glossary is consistent.)
- Are the definitions suitable for this book and its audience? Check especially for terms that have multiple definitions, some of which might be irrelevant in this context. (In the glossaries I was editing, some of the definitions applied to the operating system on which the product was used, but other definitions applied only to a different operating system!)
- What should be in the introduction to a glossary, when and why? Do you need to acknowledge the source of your definitions? Should you tell your readers what the glossary covers, and what it doesn’t cover? (For example, in a book about an accounting system, you might choose to include computing terms, but not accounting terms, unless the accounting terms are used in a non-standard way in the book. You could reasonably assume that the readers of the book are familiar with accounting, but not necessarily familiar with computers.)
There are no hard-and-fast rules to provide answers to these questions, but you (or your company) need to decide what rules you are going to follow, and then make sure you follow them.
Last updated 23 November 1998