Tag Archives: entry

26 tips for planning, writing and editing a glossary

By Hazel Bird

Glossaries are commonly found in a huge variety of publications, from textbooks to technical reports and from encyclopedias to essays. A good glossary can serve a number of purposes that benefit both writers and readers:

  • provide a quick reference to key concepts
  • avoid the need to duplicate definitions of key concepts in multiple locations
  • increase the accessibility of a text and thereby avoid alienating less knowledgeable readers
  • enhance the experience of more knowledgeable readers by avoiding cluttering a text with what may (to them) be basic definitions
  • help groups of co-authors to write consistently on a topic.

But a good glossary is too often an afterthought – thrown together at the end of the writing process with little consideration of how it can help to underpin a text and amplify its authority.

This post looks at how to plan, write and edit a glossary that will enhance a text and be helpful to readers. But first, a post on glossaries would be remiss if it didn’t include its own glossary:

DefinitionThe part of a glossary that tells readers what a term means.
EntryOften used to refer to a term and its associated definition as a whole.
GlossThe verb form of glossary. If you gloss a term, you provide a definition of it.
GlossaryA list of definitions of technical terms used in a text.
TermA word deemed to be of sufficient importance or complexity to require an entry in the glossary.
TextThe larger body of words of which the glossary is a part (eg a book).

It’s worth saying that although the stages below can be a helpful way of dividing up work on a glossary, it makes sense to keep all the stages in mind at all times. For example, it doesn’t hurt to decide your preference on capitalisation during the planning stage. And, equally, there’s no point developing a comprehensive plan if the writer(s) and editor(s) then ignore it!

Planning your glossary

A good glossary is based on a well-planned strategy. Questions to consider when planning a glossary include the following:

1. Why are you considering providing a glossary? Would the text genuinely benefit from a glossary as an added help to the reader? Or would the glossary primarily serve to cover up uneven, unclear or incomplete writing that would be better amended before seriously considering how a glossary would fit in?

2. What level(s) of knowledge do you expect your readers to have? Do you need to gloss basic terms or only the more advanced?

3. What level of detail do you want your definitions to have? It can help to set a nominal word or line limit.

4. If your text has multiple chapters, will you have one central glossary or chapter-specific glossaries? If you prefer a central glossary, do the chapters use the same terminology or will any revisions be required to standardise terms that will appear in the glossary?

5. If your text has multiple authors or topics, how will you ensure consistency between their glossaries? Would it be helpful to provide a few sample glossary entries (taking account of the suggestions for writing and editing below)?

6. Will the glossary be allowed to define abbreviations or will these appear in a separate list? For example, if your text talks about JSON, do you want to have (a) a glossary entry that provides the full form (JavaScript Object Notation) and then talks a bit about its use in software development, (b) an entry in a separate list of abbreviations that simply provides the full form or (c) both?

7. Will cross-referencing between glossary terms be allowed (or required)? For example, the glossary of glossaries at the start of this post uses italics to cross-reference to other entries. This lets readers know a term is explained elsewhere in the glossary (and often means you can be more economical in your definitions).

8. Where will the glossary appear and how will readers access it? Common schemes include: (a) simple standalone glossary with no links to the text, (b) standalone glossary with hyperlinks and/or special formatting (e.g. colour or bold) on glossary terms in the text and (c) glossary entries on the same pages as their associated terms (common in textbooks). Which would be most suitable for your text?

9. How will readers know your glossary exists? Will you put a note at the start of the text (or even at the start of each chapter or section, if your text has subdivisions)? What will be the best balance between making information easily accessible and avoiding clutter? You can’t assume that readers will understand that bold (for example) means that there is a glossary and that the bold word is glossed within it – you have to tell them what the bold means.

Writing your glossary

Once you have a solid plan to work from, you can actually start writing your glossary (or ask your contributors to submit entries to you). Following are some do’s and don’ts of glossary writing:

10. Do consider how your terms are actually used in the text. There’s no point having a glossary term for ‘information architecture’ if the text only ever refers to ‘architecture’.

11. Do use parallel structure. For example, will you start definitions with ‘X is an …’ or just ‘An …’? This issue is connected with presentation too: usually, the longer form is only necessary if you plan to run the glossary terms into the definitions. For example:

Agile  A method of software development that occurs in stages, with the product evolving as the project progresses. (Separated style)

Agile is a method of software development that occurs in stages, with the product evolving as the project progresses. (Run-on style)

12. Do think about the grammatical forms of words. For example, it might look inconsistent to have a definition for ‘coder’ (noun) alongside one for ‘developing’ (verb). Unless there’s a good reason, it might read better to choose either ‘coder’ and ‘developer’ or ‘coding’ and ‘developing’.

13. Don’t use the word in the definition – usually. Sometimes it works, where you decide to explicitly re-state the term in the definition for grammatical reasons (as I did above in my definition of ‘gloss’). But usually it’s bad practice as it assumes knowledge on the part of your readers that they might not have. For example, you might include the following definition:

software development  Using computer code to develop digital applications and infrastructure.

Here, you’d only really have glossed ‘software’ and you’d be assuming your readers know what ‘develop(ment)’ means in the context of computing.

14. Don’t make the definition so complicated that the reader has to look it up to understand it. (Or, if you need to use technical terms, consider defining them elsewhere within the glossary and including cross-references – see point 7 above.)

15. Don’t include Wikipedia content (or similar) – anyone can do an internet search for a generic Wikipedia definition. Glossaries add value for the reader by framing each term in a way that is nuanced to reflect the content of your text.

16. Don’t quote other sources in your definitions, unless they offer uniquely relevant perspectives or you have a special reason for doing so. This can reduce the sense of authoritativeness of your text.

17. Don’t repeat definitions from the text. Readers will be frustrated if they go to the glossary in search of further explanation and just find what they’ve already read.

Editing your glossary

Glossary editing often takes place over multiple stages. First, the person who wrote the glossary (or who is collating it from multiple contributors) checks that the content is suitable and that there are no glaring holes or inconsistencies of approach. Then, another person (often a copyeditor or proofreader) conducts a more zoomed-in check to sculpt the glossary into its final form. Each will likely need to look at the following points to some degree:

18. Does the glossary adhere to each point of the plan? If not, is the divergence acceptable (perhaps something has changed since you created the plan) or do you need to adjust the entries?

19. Is the coverage logical, consistent and comprehensive? For example, have all terms of the same type been included? (So, if you’ve glossed XML, you’ll probably want to gloss HTML too if your text uses both terms.) Are there any often-used terms that are not glossed but should be? If one of the glossary’s functions is to gloss little-used terms to avoid cluttering the text with explanations, have all of these been identified?

20. Will your alphabetisation be intuitive to readers? For example, will your readers expect to find a general explanation of the syntax used in computer coding under ‘language’ or ‘programming language’?

21. Do you need any ‘see’ entries? If readers might look for the same term under two different phrases, you could choose to include both. For example, you could have a definition of the term ‘language’ but also cross-reference to it further down as follows:

language  Words and other notation used according to a pre-defined structure to create computer programs.

programming language  see language

22. Is every term in the glossary actually used in the text? See also points 10 and 12.

23. Have the glossary terms been indicated in the text where applicable (see point 8)? And are you doing this on every occurrence of each term or only (for example) at first use in the text or chapter?

24. Is the punctuation consistent? For example, will your definitions end with a full stop? This may depend on the length of the definitions. Single-sentence glossaries can end with nothing, but multiple-sentence glossaries usually look best with full stops. If you have a mixture, it’s best to be consistent and include full stops for all of them.

25. Is the capitalisation consistent? Will you capitalise all of your glossary terms (eg ‘Debugging’ and ‘Python’) or only proper nouns (eg ‘debugging’, but ‘Python’)?

26. Does each definition read well and follow whatever spelling and other stylistic conventions have been used in the main text? When they think about what goes into editing a glossary, many people jump straight to this point. But, in reality, it’s just the last item in a long list of other considerations.

Planning, writing and editing a good glossary is a complex and time-consuming process. Throwing together a glossary at the last moment is a wasted opportunity and may even detract from the reader’s experience – for example, by raising expectations that are not met (eg because the glossary is of poor quality and isn’t tailored to the text) or creating frustration (eg if the glossary is difficult to access or navigate, or equivalent terms are not glossed).

Thinking about your glossary from the start of the creation process will make it an integrated and cohesive part of your text, and enhance the text’s value and authority for your readers.

Hazel Bird is a project manager, copyeditor and proofreader who has happily edited glossaries that followed all of these tips and others that followed none. She regularly works on computing books (hence the examples above) but also edits widely across business, public sector and academic publishing.

 


Have you seen our recent focus paper by David Crystal on why it’s worth using a professional editor? It’s one of CIEP’s many fact sheets and focus papers for editorial and publishing professionals.


Photo credits: Open book by by Jonas Jacobsson; Software development by Hack Capital, both on Unsplash

Posted by Abi Saffrey, CIEP blog coordinator.

The views expressed here do not necessarily reflect those of the CIEP.