When subject matter experts create content related to your product, you're guaranteed high-quality documentation. However, SMEs often use language that may differ significantly from your customers' language.
Technical documentation typically includes technical terms, abbreviations, and even jargon, which can reduce the readability of your content. To address this, the best approach is to create a glossary accessible to both customers and in-house users.
This blog will elucidate the significance of glossaries, outline their benefits, and provide insights on how to create them.
What Is a Glossary?
Let’s try to explain what a glossary is with an example. Some companies provide all the documents with status marks, such as ACC, N/A, PI, etc. When a newbie comes across such abbreviations, there is always a moment of puzzlement, usually followed by an attempt to guess the meaning from the context.
While for ACC, the most obvious equivalent is ‘accepted,’ in the case of N/A, it can be ‘not available,’ ‘not accepted,’ or ‘not applicable.’ The worst thing is PI – no context will help you understand that it is actually ‘Accepted with punch items.’
A glossary is a handy way to solve readability problems that occur due to the use of technical terms and jargon in your documentation.
A glossary will save you a lot of time, as you won’t have to guess meanings from context. Moreover, it will help you avoid mistakes, as in the case of N/A or PI abbreviations.
In technical documentation, the bulk of terminology may consist of simple terms that do not require giving definitions or explanations to the customers or the company employees. But some terms are very specific and, at the same time, very frequently used in company documents. These terms may be a real headache for your readers.
A glossary is an approved list of terms, conventional shortenings, and abbreviations often used in your documentation. All the items in the list, just like entries in a dictionary, are given in alphabetic order and provided with definitions.
The only difference from a dictionary is that a glossary is product/project/company-specific. It contains only terms related to the product, project, or used in the company.
In addition, a glossary should contain neologisms – terms coined by technical writers or developers to describe a new phenomenon. For example, ‘conversational programming’ can be defined as a neologism as it describes a programming process typical for new machine tool controllers and reminds us of a dialogue between the machine and the human operator. However, some readers may be unaware of the meaning, so don’t forget to include this entry (or a similar one) in your glossary.
Advantages of a Glossary
A glossary will streamline the work of your technical writers. It will allow them to work in sync using the same terminology throughout all your documentation.
A glossary will relieve your customer support service by deflecting repeated questions from users. With a glossary, readers will no longer have to write to the support service. They will find the information directly on the site. As a result, customers will enjoy your content without losing time searching for the meaning of terms.
On the whole, a glossary improves the readability of your content both on internal and external levels, as the information can be used internally by technical writers and externally by customers.
In addition to readability, such UX parameters as findability and navigability will be improved as well. A glossary will save you a lot of time, as you won’t have to guess meanings from context and travel from page to page by clicking on the links.
Another advantage of glossaries is facilitating the employees’ onboarding. A glossary will help the newly hired employees absorb new information. In a glossary, the information is presented in a concise and simple way, and the new hires should be trained to consult a glossary as often as possible.
Summing up, a glossary is part of the product knowledge (the written content that educates internal and external users). Glossaries highlight the most important and complex points of the products/services for both tech writers and consumers.
Creating a Glossary
Glossaries are often part of the general documentation package supplied under a contract. Some companies already have glossaries. Others don’t. So, to create a glossary, you need to follow these rules:
- The entries in a glossary should be arranged in alphabetic order.
- If it is an online glossary, add links to the relevant entries and articles. This will allow users to quickly navigate between pages on your website.
- When compiling a glossary, start with arranging the most relevant terms. Don’t try to cover as many terms as possible. Focus on the product-specific terminology. Bear in mind that your readers already have a certain background, and there is no need to explain simple things.
- A glossary should be compiled in consultation with subject matter experts.
- Do not hesitate to review and update the glossary by adding or deleting terms, and editing the existing definitions.
After you have created and published your glossary, you will have to familiarize your employees with it. Probably, you will have to hold a training for this purpose. Don’t forget to emphasize the importance of consulting the glossary. You may also encourage your co-workers to participate in glossary creation and updating.
ClickHelp as a Glossary Creation Tool
ClickHelp is an online documentation platform that provides great opportunities for managing product-specific terminology. In ClickHelp, you can create glossaries using different methods.
The simplest way is to create a set of articles and arrange them in alphabetic order with a letter index. While creating content, you can create links to these articles. You can also use these articles as snippets, inserting them into the text whenever the relevant term appears.
Another approach is to use the information from the glossary article as a dropdown or popup text. This is very convenient for the readers, as they won’t have to search the glossary – the information will be available right on the page.
The problems of searchability and findability issues can also be addressed by creating taxonomies. These are metadata labels applied to the content. In ClickHelp, you can generate multiple index keywords, similar to labels or taxonomy tags, which are used in reference to the content. As a result, a list of references is created, making it easier for readers to find information.
When index keywords are assigned for a topic, the full-text search engine detects them, indexes them, and assigns them a higher relevance weight. This enables users to find the most relevant content including special keywords, acronyms and even informal names of the features that cannot be used in the topic text.
Index keywords allow you to index the entire company knowledge base and make information search a multi-dimensional process, rather than a ‘vertical’ one, as is the case with information arranged in folders.
Taxonomy-based search helps you sort and classify your content regardless of its location in the folders. Index keywords allow users to conduct semantics-based searches rather than searching by location. This is possible due to a superstructure (metasystem) that is built with the help of tags.
As a result, the findability feature of your knowledge base improves. Technical writers can expedite the content creation process, and product users quickly find answers to their terminology-related questions.
Conclusion
A glossary offers an excellent way to manage terminology, saving both users and technical writers valuable time that might otherwise be spent on context searches. It is a valuable resource not only for documentation but also during employee onboarding and for keeping the team updated on the latest product information. By creating a glossary, you ensure that your published documentation maintains uniformity and precision in technical terminology.
Good luck with your technical writing!
ClickHelp Team
Author, host and deliver documentation across platforms and devices