How to write a glossary (with examples)

A good glossary increases a text’s accessibility and cements its authority. Creating a high-quality glossary requires three stages: planning, writing and editing. Learn how to write a glossary with my 24 tips.

Many publications have glossaries, from textbooks to technical reports and from encyclopedias to essays. Glossaries can also be standalone resources – for example, I maintain a UK charity glossary for writers and editors. As a professional editor of books and reports that include glossaries, I’ve seen plenty of glossary examples and I’ve had many opportunities to see what works (and how the writers could have saved themselves trouble by planning their glossary differently!).

This post first looks at why a good-quality glossary matters. It then provides a glossary example and breaks the glossary-creation process down into three stages:

1. Plan the glossary
2. Write the glossary
3. Edit the glossary

When you follow these steps, your glossary is more likely to enhance your text and help your readers.

Why a good-quality glossary matters

In many cases, a glossary is a vital piece of supporting content that can transform a reader’s experience of a text. However, at the end of a long and arduous writing process, there’s a risk that a glossary will be an afterthought – thrown together with little consideration of how it can help to underpin the text and amplify its authority.

A good glossary can serve a number of purposes that benefit both writers and readers:

• Provide a quick reference to important concepts
• Avoid the need to explain the same terms again and again
• Make a text more accessible, so readers of all abilities feel welcome
• Make a text more appealing to knowledgeable readers by separating out what may (to them) be basic definitions
• Help groups of writers to use terminology consistently

As you’re writing your glossary, keep these principles in mind. Doing so will help you to predict your readers’ needs and ensure you’re meeting them.

Glossary example

Before we examine the three stages, it’s important to understand the elements of a glossary. Here’s a glossary example with labels on each part:

In addition to these four concepts (entry, definition, term and cross-references) and the word glossary itself, you need to be aware of the terms gloss and text. Here’s a full glossary of glossaries that you can use as a quick reference:

Cross-reference	A part of a definition that refers to a different term in the glossary.
Definition	The part of a glossary that tells its users what a term means.
Entry	Often used to refer to a term and its associated definition as a whole.
Gloss	The verb form of glossary. If you gloss a term, you provide a definition of it.
Glossary	A list of definitions of technical terms used in a text.
Term	A word deemed to be of sufficient importance or complexity to require an entry in the glossary.
Text	A larger body of words of which the glossary is a part (e.g. a book). Not all glossaries are part of a text – some are stand-alone publications.

How to plan a glossary that will meet its users’ needs

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 users of your text genuinely benefit from a glossary? Be honest about why you’re considering a glossary. If your motivation for including a glossary is (partially) to cover up uneven, unclear or incomplete writing, it might be better to revise the text first. Then you’ll have a better foundation for deciding whether you need a glossary.

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

3. What level of detail do you want your definitions to have? It can help to set minimum and maximum word limits.

4. If your text has multiple writers or topics, how will you ensure consistency? It may be helpful to create a draft glossary for your writers to use. This draft can be refined as the team writes. It can then form the basis for a final glossary to be included in the text.

5. 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?

6. Will cross-referencing between glossary entries be allowed (or required)? Cross-references let users know a term is explained elsewhere in the glossary. They often allow you to be more economical in your definitions. In a printed publication you might use italics or bold for cross-references. In a digital publication you might use hyperlinks (I do this in my charity glossary).

7. How will users know your glossary exists? If your terms are hyperlinked, users will clearly be able to see that they can click on them for more information. And in a printed publication, if the glossary definitions will appear on the same page as the terms (perhaps in a sidebar), the existence of the glossary will also be obvious. But in all other cases, you’ll need to think about how users will know your glossary exists. You can format glossary terms in a special way (e.g. bold or italic) in the text. But can you expect your users to know what this formatting means? Or should you put a note at the start of the publication (or perhaps at the start of each chapter or section) to explain the formatting and where the definitions can be found? What will be the best balance between making information easily accessible and avoiding clutter?

How to write a glossary so it’s authoritative and clear

Once you have a solid plan to work from, you can actually start writing your glossary. Here are some dos and don’ts to maximize your glossary’s authority and clarity:

8. Do consider how your terms are used in the text. For example, there’s no point having a glossary term for ‘information architecture’ if the text only ever refers to ‘architecture’.

9. Do use the same structure for each entry. Pick between separated style and run-on style, and use it throughout your glossary. Here’s a glossary example of separated style:

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

And here's a glossary example of run-on style:

Agile is a method of software development that occurs in stages, with the product evolving as the project progresses.

10. 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’.

11. 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 near the start of this post in my definition of ‘gloss’). But usually it’s better for accessibility not to do this, as it assumes knowledge on the part of your users that they might not have. For example, consider this glossary example:

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

In the above glossary example, we’ve only really glossed ‘software’ and we’re assuming users will know what ‘develop(ment)’ means in the context of computing. Now consider this glossary example:

software development Using computer code to construct or alter digital applications and infrastructure.

This second glossary example works better because it explains both parts of the term.

12. Don’t make the definition so complicated that users have to look words up elsewhere to understand it. Or, if you need to use technical terms in a definition, consider defining them elsewhere within the glossary and including cross-references.

13. Don’t include Wikipedia content (or similar) – anyone can do an internet search for a generic Wikipedia definition. Original, unique glossaries add value for their users by framing each term in a nuanced way that reflects the content of the text.

14. 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 authoritativeness of your text.

15. Don’t repeat definitions from the text. Users will be frustrated if they go to the glossary in search of further explanation but only find what they’ve already read.

How to edit your glossary to maximize its usefulness and accessibility

Glossary editing often takes place over multiple stages. First, the person who wrote the glossary (or who is collating it from multiple contributors) should check that the content is suitable and that there are no glaring holes or inconsistencies. Then, another person (often a copyeditor or proofreader) should conduct a more zoomed-in check to sculpt the glossary into its final form.

It can be helpful for each person to consider the following points:

16. 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?

17. 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. And 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?

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

19. Do you need any ‘see’ entries? If users 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’, as in this glossary example:

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

And then you could cross-reference to it further down, as in this glossary example:

programming language See language.

20. Is every term in the glossary actually used in the text? It’s worth doing a final check to ensure the glossary still corresponds with the text.

21. Have the glossary terms been indicated in the text where applicable (e.g. with formatting or hyperlinks)? And are you doing this on every occurrence of each term or only (for example) at first use in the text or chapter?

22. 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 definitions can end with no punctuation, but multiple-sentence definitions usually look best with full stops. If you have some single-sentence and some multi-sentence definitions, it’s best to be consistent and include full stops for all of them.

23. Is the capitalization consistent? Will you capitalize all of your glossary terms (e.g. ‘Debugging’ and ‘Python’) or only proper nouns (e.g. ‘debugging’ but ‘Python’)?

24. 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. While it’s important, it’s only the last item in a long list of other considerations.

How to write a powerful glossary

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 users’ experience. For example, it might raise expectations that aren’t met (if the glossary is of poor quality and isn’t tailored to the text) or create frustration (if the glossary is difficult to access or navigate, or important terms are missing).

A good glossary can be a powerful complement to your text that helps users get the maximum benefit from it.

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

Remember to plan, write and edit – don’t skip any of the stages. Get in touch if you’d like support with constructing a glossary that does your text proud.

---

For another editorial perspective on what goes into creating a top-quality glossary, check out ‘Editing a scholarly bilingual glossary’ by editor Carla DeSantis. Carla offers a fascinating case study of an edit of a 168-page English glossary of Nahuatl words, phrases, and place names.

This is an edited version of a post originally published on the Chartered Institute of Editing and Proofreading blog as ‘26 tips for planning, writing and editing a glossary’.