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.
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.
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.
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.
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.
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.
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.
The template to create a list entry can be very simple. It should contain at least the following elements.
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:
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.
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.
It might be very helpful if the product documentation contains domain-specific, technical or scientific terms.
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.
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.