Manage a Glossary in Fluid Topics - Fluid Topics

Category
How To
Audience
public

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).

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.

  • Teradata

    • 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.
  • Hexagon Geospatial

    • Configuring different font weights and indentations helps separate terms and descriptions.
  • Fluid Topics

    • 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.