- Books, Literature, and Writing
Writing Glossary Definitions
On Writing a Glossary
Writing glossary definitions is not as straightforward as most people consider it to be: most glossaries suffer because of this misunderstanding. A glossary is not simply an informal dictionary, and so it must not be treated as such otherwise your readers may misunderstand what you are writing about.
This article talks about defining concepts for your glossary, provides rules to follow and tips for success, exercises to learn from, and a make-believe example of a glossary.
Intelligence Law Glossary
Have you ever written a glossary?
Defining a Concept for a Glossary
The first step to writing a good glossary definition is to make sure that you are defining—and not describing—a unique concept that will add value to your reader’s understanding of the document or topic for which you are writing the glossary.
Write your definitions in this general structure (modify to be realistic, please, don’t follow this blindly):
TERM: A [type of high-level concept] that [is different from other concepts in this way].
If you really think about it, almost all concepts are ultimately a subset--or literally a type of--one of these high-level concepts:
server, client, ball, child, fish
condition, status, feeling, opinion, thought
installing, upgrading, configuring, adjusting, childbirth, sneezing
software, hardware, cloth, water
security, prerequisite, Northern lights, electricity, gravity, magnetism, feeling, erosion (which might be instead/in addition defined as a process, depending on your use case)
toolkit, concatenation, continuum, set, series
government, education, mathematics, law enforcement
Other (Use very sparingly)
Physics is a type of science and so is biology. Types of physics include optics, thermodynamics, and both Newtonian and non-Newtonian physics. So, what is “science”, from our list of high-level concepts? It is a phenomenon, which is probably not necessary to mention in most glossaries.
If I’m defining the term “optics”, as in the science of optics not as in the physical lenses used to interact with light, I could write, “The physics of electromagnetic radiation—or light—and how it behaves and interacts with objects in the universe.” Then, I could go on to describe how “optics” is used in the text for which I am writing the glossary—giving examples as-appropriate. The level of technical detail you provide and the terminology you use should depend on the level of understanding of your audience (the readers of your glossary and the corresponding text for which you are writing the glossary).
Tips for Success
- You can use words in your glossary that are not in your text—simply include the word/phrase used in your text and cross-reference the reader to where you have defined the core concept (“Term: See concept”).
- You may need to modify the initial term you are defining to fit the purpose of the glossary. For example, instead of defining “access,” you might want to define “access privilege,” which is more specific and just as easy for the user of the glossary to locate.
- You may need to add terms to make your work easier—this isn’t cheating, and you probably don’t need to worry if the exact term isn’t used in the main text for which you are developing the glossary. Use cross-references from the actual to the defined concept if in doubt!
- Generally, the shorter the definition, the more correct it is.
- The ideal definition is
- one sentence/phrase long and
- MUCH shorter than a corresponding description or explanation would be.
- Write actual definitions, not descriptions, explanations, or examples, of how each concept is used in your work. However, once you have defined the term, you may also include descriptive/explanatory text if it is useful in helping the user to understand the concept. Cross-references to related terms help, too.
- Use complete sentences if it makes sense, such as for a formal glossary for a formal piece. However, incomplete sentences, especially for the first defining statement, are acceptable in most glossaries.
- Only define singular terms, never plurals, or your glossary will become messy and the concepts will become muddied. For example, “cattle” is really a plural meaning "a group of more than one bovine"—there is no singular word that is gender-neutral in the common vernacular. In this case, consider entering “cattle” but defining it as a group of cows and/or bulls, or better yet cross-reference the concepts “cow” and “bull”, where you actually define the terms, in a formal glossary.
- Use lowercase for all words that are not proper nouns or acronyms, so that you can tell the difference between what should and shouldn't be capitalized.
- Include cross-references to related terms. Links/page numbers aren't necessary for glossaries shorter than one page—just list the term the reader should go to for the definition. But, for longer glossaries, include page numbers and hyperlinks when appropriate to make it easy for your reader to find their information, which is the whole point of including a glossary!
- Think about each glossary entry as a “concept”—an entity unique in all the world, defined here by you to differentiate it from all other concepts. If two “concepts” have identical definitions, then either you need to write more specific definitions or make the “two” concepts alternate names for each other. (Literally synonymous, not just "sort of synonymous" in the Roget’s Thesaurus sense of “synonymous”.)
- Never use the term (or variations of it) to define itself.
Incorrect: “Term: A term/synonym that….”
- Don’t repeat the term at the beginning of the sentence that defines it.
Incorrect: “Term: Term is a type of ….” Correct: “Term: A [type of higher-level, previously defined or an obvious concept]….”
The Twitter Glossary
“Exercises for the Student”
If you can figure out how to define the following concepts, you’re on the right track:
- What’s the difference between “number” and “numeral”?[i]
- What’s the difference between “numeral” and “letter”?[ii]
Others to try on your own (answers are an exercise for the student):
- “color” and “hue”
- “smooth” and “flat”
- “thick” and “dense”
- “software” and “program”
- “baby” and “infant”
- “several” and “many”
- “finger” and “thumb”
[i] “Number” is how many things there are that you’re talking about (it would fall into the category of “phenomena”); “numeral” is a graphic representation of “number”.
[ii] “Numeral” represents a number of objects; “letter” is one of the 26 ABCs that together form the alphabet of the English language.
How Did You Score?
Did you get the answers to the sample exercises correct? How confident are you that you could define the words in the "exercises for the student"?
Sample Scenario: Lead-in to a Hypothetical Glossary for Software Product Documentation
This is a lexicon of the specific language needed to use the ACME system to DO SOMETHING.
Users of this system may be familiar with:
- ACME’s previous systems
- other similar government and industry systems
- all—or none—of the above
For clarity and accuracy, then, this glossary defines terms used in the ACME System documentation, erring on the side of including significant concepts and terms, even “obvious” ones.
ACME System—Software produced by ACME Software, Inc., to DO SOMETHING for SOMEONE in the SOMETHING and SOMETHING ELSE industries.
Administrator role—The role of the person who is responsible for installing, updating, backing up, and ultimately maintaining ACME System software.
crash—The process in which the ACME System software fails in some way that causes the User’s computer to shut down unexpectedly, possibly generating one or more error messages during the process.
nonsense—A common condition in which a user attempts to accomplish something that ACME System software was not designed to do and is therefore unable to perform.
productivity—The measure of tasks the User accomplishes in a certain period of time that may or may not be quantitatively specified; if many tasks are completed in a short period of time, productivity may be said to be “high”; if fewer tasks are completed than expected for the period of time, productivity may be described as “low.” Note that productivity is affected by all of the following: User ability, network/system stability and traffic volume, computer processor speed, or ACME System capabilities for the particular task the User is performing.
role—A set of tasks, actions, and/or common patterns of behaviors exhibited by individuals interacting with ACME System software to accomplish a particular end-result; one of several general purposes for which a person may interact with ACME System software. User role and Administrator role are examples of this.
User role—The role of any person who is accessing and performing tasks using ACME System software.
Having written and edited 10,000+ glossary definitions in dozens of topic areas over my career as a technical writer, I have studied and honed the skill of writing effective glossary definitions to a fine point.
This article provided an easy method for you to follow to create effective, informative glossary definitions that your readers will be able to understand. Writing a high-quality glossary definition is a specialty technical writing form, but anyone can master it!
Follow this advice, within reason, and your glossaries will be easier to develop and your readers will be better able to understand each concept/term you are defining, which is the ultimate goal of creating a glossary.
- Write a Strong Copyright Notice to Protect Your Work
Copyright notice: three or four things you need to put on documents, software, presentations, and anything else you publish, whether for yourself or an employer. Learn how to write a copyright notice.
- Word Use: Percent vs. Percentage
A simple explanation of the difference between the two often-misused words "percent" and "percentage" and when you should and shouldn't use them.
- Improving Your Writing Skills ASAP: A How-to
A quick, cheap, and relatively painless way to improve your writing: read Strunk and White's "The Elements of Style". A writing quiz checks your knowledge of common blunders made in English writing.
- Words that are Most Misused in the English Language
Many words are commonly misused in the English language, through ignorance, expediency, typo, or colloquial error. This article is in answer to a question asked by CWanamaker http://itiny.in/kq8IDz
- Multipublishing in Corporate Communications
"Multipublishing" means publishing the same information in more than one place in a set of communication pieces. Multipublishing is very expensive to develop, maintain, update, and obsolete.
- Spelling Checker and Grammar Checker Software Has a Place in the Writing Process
Computer spelling/spell checkers and grammar checkers are useful, to a point. Take advantage of your computer's abilities to help you write better, but follow-up with human editing for best results.
About the Author
Information about the author, a list of her complete works on HubPages, and a means of contacting her are available over on ==>Laura Schneider's profile page. But wait--please leave ratings and any comments you have about this article so that it can be improved to best meet your needs. Thank you!
All text, photos, videos, and graphics in this document are Copyright © 2014 Laura D. Schneider unless indicated otherwise or unless in the public domain. All rights reserved. All trademarks and service marks are the property of their respective owners.