A glossary lists the specific terms and describes it in a user-friendly language. It can be used for complex, domain-specific products and software applications.
What is a glossary?
The definition of a glossary is according to wikipedia “an alphabetical list of terms in a particular domain of knowledge with the definitions for those terms. Traditionally, a glossary appears at the end of a book and includes terms within that book that are either newly introduced, uncommon, or specialized.“
A bilingual or multilingual gloss, a so-called dictionary, can be used to list the terms in one language and describe their meaning in one or multiple foreign languages.
It can be said that a glossary typically contains explanations of concepts relevant to the specific topic. So they can also be compared to an ontology that categories different terms and their relationships.
How to create a glossary?
Step 1: Collect
When creating the documentation for a software product or web application, specific terms that are related to the domain of the product, should be noted down in a list. Check the different types of documentation for foreign or technical terms that might be unknown to a new user or reader.
Step 2: Create initial list
This list can be used to create the initial list. Go through the initial list, and check for duplications e.g. by synonyms, typos and remove non-related terms.
Create the list e.g. in Microsoft Word or Excel, or Google Docs, and sort the entries alphabetically.
Step 3: Write the entries
For each of the entries, write a short explanation of the concept or meaning of the term. Compared to the document type explanation this should be very short and only contain 1-2 sentences. Use synonyms, antonyms and – if helpful – examples. The next section provides a free glossary template.
If a specific explanation or reference page exists, reference this.
Step 4: review by external reader
Check with external people e.g. from your customer or reader base and let them read through the gloss. They should mark unclear entries and suggest missing entries that might be helpful when reading through the documentation of your product.
Step 5: publish and link
The final version should be published online in the documentation tool, or at the end of the user manual. For online documentation, when using such a term from the enumeration, a link to the entry of the online glossary should be added.
Glossary template
The template to create a list entry can be very simple. It should contain at least the following elements.
- Term: word or fragment
- Definition: short description of the meaning of the term; not longer than 2-3 sentences
- Alias: (optional) similar terms or synonyms
- Category: (optional) in case of multiple glossaries or a big glossary, the terms might be categorized
- Further reading: (optional) list of links to additional pages in the online documentation that are related to the term and e.g. explain the usage or a specific functionality in your software product
How can glossaries be used in software documentation?
If the software product uses many specific terms and concepts, a register is very helpful for the user and reader of the documentation.
Atlassian, the company behind Confluence and Jira, describes on their website, how the wiki and documentation software Confluence can be used to create an internal-oriented content design glossary. Besides a short description, it provides a very basic template that can be used for Atlassian Confluence.
The page is referring to the usage for design, but can be generalized and used also for other internal and external documentation tasks. The list entries are ordered alphabetically and structured with the following 4 columns:
- Name
- Definition
- Guidelines
- Example
Typical questions
How to create a glossary in Word?
Creating a glossary in Microsoft Word, Microsoft Excel or even in Google Docs is quite simple. You can use a table with 2-4 columns and create a new row for each term. Then you can export the result e.g. as PDF and use or reference it in your documentation.
What is the difference between a glossary and a dictionary?
Glossary vs dictionary is similar, where dictionary is mostly focused on different languages, where the term in one language is listing the related terms (e.g. synonyms) in a foreign language.
When to use a glossary?
It might be very helpful if the product documentation contains domain-specific, technical or scientific terms.
What is one benefit of including a glossary at the end of a text?
If the gloss is part of the manual or documentation pdf, the reader can directly check it if when reading an unknown term. If the glossary is separately stored and published externally, the user has to switch to the other document or pdf file, and return to the original text.
Need more information about using glossary for software documentation?
If you have a question or need some more information about glossaries, reach out to us. Subscribe to our newsletter to get more information and content about multilingual documentation.
This page is part of the comprehensive list of documentation types.
[Continue reading]