Overview
Providing a glossary as part of the documentation aims to help users in the following ways:
- It defines concepts, acronyms, and abbreviations that are relevant for a particular product, process, service, or field.
- It ensures consistency, thus increasing the reliability of the documentation.
- It promotes shared understanding among readers, content creators, and different teams.
Procedure
The following recommendations can help create user friendly glossaries.
Content
-
A single-language documentation portal needs only one glossary. Continuously update the glossary based on user feedback and whenever adding new content to the portal.
-
Make sure the glossary meets the audience's needs. A technical audience is more aware of field-related abbreviations and acronyms than non-technical end-users.
-
Use plain, clear language. Do not use glossary terms or additional abbreviations and acronyms in the definitions. Readers should not have to scroll back and forth in the glossary.
-
For multi-language portals, keep up-to-date glossaries for each language.
-
Create a Pretty URL for each topic/entry. Pretty URLs provide a direct link to content, even when moving the content within the document structure. Search bots crawl all pretty URLs, thus improving search engine optimization (SEO).
When creating a glossary in Author-it, it is required to add a title to every glossary term. A single glossary term without title prevents the publication of the entire document.
Structure
-
The glossary's structure should make it a standalone document. Structuring each entry in the glossary as a map/topic provides the following advantages:
- Each new entry is a topic.
- Topic titles are the search result titles. This helps display the glossary topic as the first result when searching for a term. Topic titles are more relevant than topic content.
-
Adding an abbreviation and a more detailed form to the title improves the search experience.
-
Use CSS to customize content. Content customization helps readers distinguish between the glossary and all other content.
- Use a separate font family for the glossary.
- Customize font size and weight for glossary titles and descriptions.
- Add a watermark image in the background.
Examples
The following public glossaries are good examples in terms of content, structure, and customization.
-
- Using CSS to configure different font sizes helps separate terms and descriptions.
- Configuring different font colors helps separate section titles.
- Defining a Pretty URL for the glossary improves availability and SEO.
-
- Configuring different font weights and indentations helps separate terms and descriptions.
-
- The glossary is divided into two sections: Abbreviations and Definitions.
- Configuring different font sizes helps separate terms and descriptions.
- Defining a Pretty URL for the glossary improves availability and SEO.