You are three paragraphs into an article and you hit a word you do not know. Not a hard word, just an unfamiliar one. An acronym, a product name, a bit of industry shorthand.
You have two options. Stop reading and go look it up, or guess and carry on. Most people guess, and from that point the rest of the page is built on a foundation they are not sure about.
A glossary exists to remove that moment. This guide covers what a glossary is, what goes in one, how it differs from a dictionary or an index, and how to write entries people actually find useful.
TLDR
- A glossary is an alphabetical list of specialised terms with short definitions, written for a specific document, product, or field.
- It differs from a dictionary because it covers only the terms that matter in one context, defined the way that context uses them.
- A good entry is one or two sentences, written in plain language, and avoids using the term inside its own definition.
- Glossaries belong wherever readers meet unfamiliar words. Documentation, textbooks, contracts, onboarding material, and technical reports.
- The most common mistake is defining jargon with more jargon.
What Is a Glossary?
A glossary is an alphabetical list of specialised terms with short definitions, covering the vocabulary used in one document, product, subject, or organisation.
The word comes from the Latin glossarium, itself from the Greek for a word needing explanation. Medieval scribes wrote small notes in the margins of manuscripts explaining unfamiliar Latin words, and those marginal notes were eventually collected at the back of the book. That is still roughly what a glossary is, a collection of explanations for words the reader might not know.
Three things separate a glossary from every other reference list.
- It is scoped. A glossary covers one book, one product, one industry, or one company. It does not attempt every word in the language.
- It is contextual. A term is defined the way this document uses it, which may differ from how another field uses the same word.
- It is brief. Entries explain enough to keep the reader moving, not enough to replace a full article.
What Does a Glossary Actually Do?
On the surface it defines words. Underneath it does four more useful things.
A glossary is also a small act of knowledge management. It takes something people know and writes it down so others can use it, which is what makes it explicit knowledge rather than something living in one person’s head.
It lets the main text stay readable. Without a glossary, every unfamiliar term has to be explained where it appears, which bloats the writing. With one, you use the term and let the glossary carry the explanation.
It keeps everyone using the same word. When a team agrees on definitions, people stop using three names for one thing. That matters more in large organisations than most people expect.
It lowers the entry cost for new readers. A newcomer and an expert can read the same document, with the newcomer dipping into the glossary and the expert ignoring it entirely.
It reveals gaps. Writing definitions forces you to be precise, and a term nobody can define cleanly is usually a term the organisation has not thought through.
What Goes Into a Glossary Entry?
Most entries need only two parts, with three optional extras.
| Part | Required | What it does |
|---|---|---|
| Term | Yes | The word or phrase exactly as it appears in your text |
| Definition | Yes | One or two sentences in plain language |
| Expansion | For acronyms | What the letters stand for |
| Example | Optional | The term used in a real sentence |
| Related terms | Optional | Cross-references to connected entries |
Brevity is the whole discipline here, and the same rules that make documentation readable make a glossary entry useful. Our guide to concise documentation covers how to cut without losing meaning.
Resist the urge to add more. Pronunciation guides, etymology, and long background notes belong in an article, not an entry a reader is skimming mid-sentence.
Glossary vs Dictionary vs Index vs FAQ
Four reference tools that get confused with each other, and they do genuinely different jobs.
| Tool | Answers | Scope | Sorted by |
|---|---|---|---|
| Glossary | What does this word mean here? | One document, product, or field | Alphabetically |
| Dictionary | What does this word mean generally? | A whole language | Alphabetically |
| Index | Where is this discussed? | One document | Alphabetically, with page numbers |
| FAQ | How do I do this? | Common questions | By topic or frequency |
The glossary and index distinction trips people up most. A glossary tells you what a word means. An index tells you where to read more about it. Many books carry both, sitting next to each other at the back.
Types of Glossaries
The same format serves several different purposes.
- Book glossaries sit at the back of textbooks and technical books, covering terms introduced in the text.
- Product glossaries define the vocabulary of one piece of software or hardware, including feature names the company invented.
- Industry glossaries cover a whole field, and often become reference resources in their own right.
- Internal glossaries record how one organisation uses terms, including the ones it uses differently from everyone else.
- Legal and contract glossaries appear as a definitions clause at the start of an agreement, where a defined term carries exactly the meaning given and nothing else.
- Translation glossaries lock down how each term should be rendered in every language, so a product name does not drift across markets.
Where Glossaries Belong
Anywhere a reader meets words they were not taught. The most common homes are these.
Product documentation and help centres. Every product invents vocabulary, and a customer reading a help article has met none of it before. Our guide on documentation best practices treats a glossary of key terms as part of a working style guide.
Onboarding material. A new employee’s first fortnight is largely spent decoding acronyms. Writing them down once saves that time for everyone who joins afterwards.
Academic and technical writing. Where precision matters and terms carry narrower meanings than in everyday use.
Contracts and policies. Where a definitions section is not a courtesy but the thing that makes the rest enforceable.
How to Write a Glossary Entry People Understand
Six rules cover almost everything.
Define the term without using it. “Rate limiting is the practice of limiting rates” helps nobody. If the definition needs the term, rewrite it.
Keep it to one or two sentences. A glossary entry is read mid-sentence by someone who wants to get back to reading. Length defeats the purpose.
Write for the least expert reader. If your audience includes beginners, define it for them. Experts skip entries they already know, but beginners cannot decode one written above their level.
Avoid defining jargon with jargon. This is the most common failure. Check every definition for words that would themselves need an entry.
That last point is worth dwelling on, because over-reliance on technical terms is one of the most common documentation mistakes, and a glossary written in the same register simply moves the problem.
Be consistent about form. Pick singular or plural, pick a sentence structure, and hold to it across every entry. Inconsistency makes a glossary feel unreliable even when the content is right.
Define the term as your document uses it. If your product uses “workspace” in a specific way, define that way. You are not writing a dictionary entry.
Common Glossary Mistakes
- Including terms nobody needs defined. Padding a glossary with obvious words makes readers stop checking it.
- Leaving out the ones that matter. The terms you find hardest to define are usually the ones most worth defining.
- Writing it once and never updating it. Products rename features. A glossary describing last year’s vocabulary actively misleads.
- Burying it. A glossary nobody can find is a glossary nobody uses.
- Letting definitions drift. When the same term is defined differently in two places, readers trust neither.
Frequently Asked Questions
1. How many terms should a glossary have?
As many as your readers need and no more. A product glossary often sits between 20 and 100 terms. An industry glossary can run to thousands. The right test is whether every entry earns its place, not whether you have hit a number.
2. Where should a glossary go?
Traditionally the back of a book, before the index. In digital documentation it works better as its own page, linked from your navigation, with individual terms explained where they appear so readers do not have to leave the page they are on.
3. Should a glossary be alphabetical?
Almost always. Readers arrive knowing the word and wanting the meaning, so alphabetical order is the fastest route. Grouping by theme only works when readers are browsing rather than looking something up.
4. Who should write the glossary?
Whoever owns the documentation, with review from the people who use the terms daily. Subject experts often define terms in language only other experts understand, so a writer and an expert together produce better entries than either alone. One person should own the final wording, since split ownership is how conflicting definitions creep in.
5. What is the difference between a glossary and a lexicon?
Very little in practice. Lexicon tends to describe the full vocabulary of a language or field, while glossary usually means a shorter list attached to a specific document. The words overlap enough that most readers treat them as the same thing.
6. Do glossaries help with SEO?
They can, because each term is a page or section answering a definition query, and those queries are common. The benefit is real but secondary. Write the glossary for readers first, and fold it into your wider knowledge base SEO plan rather than treating it as one.
Start With Ten Terms
A glossary is a simple idea with an outsized effect. Define the words your readers do not know, keep the definitions short and plain, and put them somewhere findable.
If you are building one from nothing, do not try to be complete. Write down the ten terms your support team explains most often, define each in a sentence, and publish. Those ten will do more work than a hundred entries nobody asked for, and you will learn which ones to add next by watching what people still ask about.
For the wider question of how that fits alongside everything else your readers need, our guide on the types of product documentation covers where each piece belongs.
Subscribe to
weDocs blog
We send weekly newsletters,
no spam for sure!
