Please see the source of this guide in the template repository.
Glossary guide
Thank you for downloading this template from The Good Docs Project! Before using the glossary template, read this template guide for information about how to complete each section. Want to explore more templates? Check them out in our templates GitLab repository.
Introduction
A glossary is a common reference document that organizes terms and their definitions. It is best practice for glossaries to only store terms that are specific to a particular industry, organization, or team. Terms or descriptions defined in an established dictionary typically shouldn't be included in a glossary.
For example, a glossary explaining web application terms should not include agricultural terms unless they have a unique meaning or use for that project, team, or organization.
Glossaries and terminology systems
A base glossary usually includes a term, definition, and abbreviation (if there is one). More complex glossaries can include additional information, including localization notes, related terms, term provenance, and more. These more advanced glossaries are called terminology systems and are covered in the Good Docs Project's terminology system template and guide.
The table below has a non-inclusive summary of information types commonly found in glossaries and terminology systems.
| Information Type | Glossary | Terminology System |
|---|---|---|
| Term | Yes | Yes |
| Abbreviation | Yes | Yes |
| Definition | Yes | Yes |
| Alternative term | No | Yes |
| Rejected terms | No | Yes |
| Related terms | No | Yes |
| Part of speech | No | Yes |
| Provenance | No | Yes |
| Notes for translation and localization | No | Yes |
| Context sentence for translation and localization | No | Yes |
| Modified on (date entry last changed) | No | Yes |
| Description of modification | No | Yes |
Why do you need a glossary?
A glossary can be very useful to an organization. It can:
- Be a "cheat sheet" for team jargon, helping onboard new contributors faster.
- Lower miscommunication caused by the use of obscure terms, or terms with multiple accepted definitions that may overlap or conflict.
- Help users better understand the language used in and about a product.
- Integrate with web pages to provide hover-over popup definitions (if saved in a machine-readable format).
- Improve accessibility of websites and pages.
- Simplify translation efforts for international teams and organizations.
Before writing a glossary
- Evaluate whether a new glossary is needed: a. Is there an existing glossary that can be revised? b. Does the identified audience require a glossary based on their knowledge level?
- Identify your audience.
- Research the most appropriate glossary format for your intended use.
- Gather terms.
- Consider the information you need for each term.
For more detailed information on the glossary writing process, refer to the Glossary Process document.
About the glossary template
About the "Term" column
The term you're defining.
Tips for gathering terms
- Consider whether the glossary will be a private team resource or available to the public.
- Select terms with a meaning specific to your audience.
- Search your existing source documents for common terms and acronyms.
- Consult the glossary's audience to find terms that aren't yet defined, or have unclear definitions.
{Optional} About the "Abbreviation" column
The term's abbreviation or acronym (if it has one).
About the "Definition" column
A short definition for the term, no more than one to three sentences.
If the definition already exists elsewhere (for example, in an online dictionary), and that definition matches your team's use of the term, use the published definition.
If an authoritative definition does not already exist, you'll need to write one. Reference the Glossary Process document for definition writing best practices.
{Optional} About the "Source" column
A hyperlink to the definition's source, if you did not write the definition yourself.
Example glossary entry
| Term | {Optional} Abbreviation | Definition | {Optional} Source |
|---|---|---|---|
| application programming interface | API | An API, or application programming interface, is a set of defined rules that enable different applications to communicate with each other. It acts as an intermediary layer that processes data transfers between systems, letting companies open their application data and functionality to external third-party developers, business partners, and internal departments within their companies. | https://www.ibm.com/topics/api |
--
Explore other templates from The Good Docs Project. Use ourfeedback form to give feedback on this template.