How do I write a glossary that helps people use a handbook while they read it?
Quick answer
Build the glossary from terms readers may encounter and need to understand—not every specialized word in the handbook. Define each term briefly using the same meaning and wording the handbook uses, then point to the section where readers can see it in context or find related instructions. Check entries against the finished handbook so definitions, capitalization, and cross-references stay consistent.
The question, the details, the next step.
How do I decide which terms belong in the glossary? I don’t want it to become a second index or a list of every word that might be unfamiliar.
Include a term when knowing its meaning helps readers understand or act on the handbook’s content. Good candidates are terms that are specific to your subject or organization, used in a particular way in the handbook, or needed to follow an instruction. A term may deserve an entry even if it is familiar to some readers, if the handbook gives it a precise meaning.
You can leave out ordinary words that are clear in context, terms that appear only once without affecting understanding, and details better explained in the relevant section. Ask of each candidate: “Could a reader misunderstand this term, or have to stop and look elsewhere to continue?” If not, the glossary may not be the right place. An index helps readers locate topics; a glossary explains what selected terms mean.
Once I have the terms, what makes a definition useful without making it too long?
Start with the meaning a reader needs for this handbook, then add only the distinction that prevents likely confusion. Use plain language and, where possible, the same wording the handbook uses. Avoid defining a term with another unexplained specialist term, and don’t use the entry to introduce a new rule or exception that belongs in the main text.
A practical pattern is: Term — short meaning. Add a second sentence only when the reader needs a boundary, example, or distinction to understand the handbook’s use.
For example, assuming a handbook uses “review window” to mean the period for submitting comments: Review window — The period when readers may submit comments on a draft. See “Reviewing a draft” for how to submit them.
That wording is illustrative, not a definition for every handbook. If the main text uses the term differently, revise the example to match that usage.
How should I point readers from an entry back to the right part of the handbook?
Use a section title readers can find, rather than a vague direction such as “see above.” If the handbook has stable page numbers, you can include them, but a section heading is often more useful when the document may be reformatted. Point to the section that explains the term in context or gives the relevant steps—not just the first place the term happens to appear.
A copyable entry format is:
[Term] — [Plain-language meaning as used in this handbook]. See “[Exact section heading]” for [context, instructions, or related detail].
Use “See” when another entry is the best place to find the explanation. Use a short “See also” only when a related entry genuinely helps readers understand the topic; don’t add a web of cross-references that sends them in circles. After headings change, revisit each reference and confirm it still points to the intended section.
What’s a simple way to check consistency when several people have written different sections?
Treat the glossary as a check on the handbook, not a replacement for editing the main text. For each entry, compare the definition with the places where the term appears. If the handbook uses the same term with different meanings, decide whether the distinction is intentional. If it is, make that distinction clear in the relevant sections and glossary; if not, align the wording before publication.
A small term sheet can help contributors stay aligned:
- Preferred term: the form used in headings and text.
- Meaning here: the concise definition for this handbook.
- Avoid or clarify: a competing term or likely ambiguity, if relevant.
- Where to look: the exact section title that explains it.
Then check spelling, capitalization, singular and plural forms, and every cross-reference against the current draft. The glossary can make the handbook easier to navigate, but it cannot resolve an unclear instruction on its own; revise the main section when readers need more explanation.
A practical checklist
Include terms that readers need to understand the handbook’s content or follow its instructions.
Leave out terms that are clear in context or better explained in the relevant section.
Define each term in plain language and match the handbook’s actual usage.
Use exact section headings for cross-references, and verify them after edits.
Check repeated terms for consistent meaning, spelling, and capitalization.
Use cross-references selectively so they lead readers toward useful context.
A few more useful answers
Should glossary entries be alphabetized?
Alphabetizing is a straightforward way to help readers scan for a term. Keep the entry wording concise and consistent within whichever layout you choose.
Should I include acronyms?
Include an acronym when readers may need its meaning to understand the handbook. Give the full form and any handbook-specific meaning, and make sure the main text introduces or uses it consistently.
What if a term has two meanings in the handbook?
First check whether the distinction is intentional. If it is, explain the separate meanings clearly and point readers to the sections where each applies; if not, revise the handbook to use the term consistently.