Why create a glossary?
Understanding the terms and acronyms that make up your company's vocabulary is an essential first step toward understanding its processes and products. It is therefore crucial to ensure that all readers share this understanding.
Fluid Topics customers often ask us how to provide this information in the form of a glossary.
The ideal solution is the one that is best adapted to your authoring process and tools. That being said, a few guidelines can help you create and publish a glossary that is easy to access and use.
Guidelines for creating a glossary
- The glossary should be substantial enough to stand alone, especially if it concerns several products.
- Each entry of the glossary should be structured as a map/topic. Advantages include:
- Easy to add a new entry (topic).
- The title of the topic is the title of the search result.
- The title of the topic has the best relevance. When searching for a word that is the title of a document, it often appears as the first result.
- Provide a title and text for each entry. The title is more relevant than the text when searched.
- The title should contain the original form of acronyms as well as a more detailed form. The search experience is improved when both appear in the titles of the results.
- Update your glossary often by adding new entries or modifying exisiting ones.
- Translate your glossary if your documentation is available in several languages.
- Create a prettyUrl for each topic/entry. This will provide a direct and unbreakable link to your content.
- If your site is open, bots will crawl all prettyUrls and make SEO easier.
- Consult these tips for making a glossary that will engage customers.
- Use CSS to customize the rendering of content in the Reader page depending on its metadata. For example, with CSS it is possible to configure the glossary's font, color, or watermark. This will help readers to distinguish between the glossary and any other document, such as a reference guide.