Searching for ways to improve the usability of your documentation? Consider developing a glossary!
Already have one? Look for ways to enhance your glossary in this post.
When users approach documentation, they are usually looking for two types of information:
- How to perform a specific task.
- What a specific UI element is used for.
One of the reasons why a UI element name may be confusing for a user is ambiguous terminology. This is especially true for multifunctional enterprise solutions that introduce their specific set of concepts or use the already existing terms in new ways. An indispensable part of documentation for such solutions is a glossary.
What is a glossary?
Glossary is a list of solution-specific terms and their meanings arranged in an alphabetical order. In fact, a glossary is similar to a dictionary, only it lists words and definitions that are relevant in the context of a specific solution.
What types of documents should contain a glossary?
Glossaries may be especially helpful in documents for highly technical and complex solutions. Very often, such types of glossaries also explain the meaning of abbreviations and acronyms.
What types of users need a glossary most?
Even if your document has up to 10 terms that may be confusing to some users, you can create a glossary. The glossary will ensure that the document author and all its users, especially new ones, are on the same page.
Glossary is also very beneficial for users with experience of similar solutions, because the same functions may be called differently. For example, the Produce option in TechSmith Camtasia corresponds to the Publish option in Adobe Captivate. In cases like these, a glossary should include the Produce term to ensure that the user clearly understands the purpose of this feature.
Which words should a glossary contain?
Your glossary may contain any vocabulary that is used in a specific meaning or can be difficult to understand.
In addition to general solution-specific terms, your glossary should explain the terms that have multiple meanings. That are the terms whose basic meaning in general English differs from the word’s meaning in the solution. For example, the word ‘ticket’ (a piece of paper that allows you to see a show, participate in an event, travel on a vehicle, etc.) is used in JIRA in the meaning of ‘task’.
However, you need to be careful when it comes to business terms used by the solution. If you are new to the business industry and are learning all the business terms for yourself, you are naturally inclined to include them into the glossary. However, being industry experts, end users know these terms well and may feel that they are spoken down to. I mean, how would we feel if MadCap Flare Help glossary included terms like DDLC and topic-based authoring?
So, we should clearly understand that even if a part of our audience are rookies that may not know what ‘nominal risk’ or ‘mitigant’ is, it is not up to our glossary to educate them in risk management. Most companies have a separate training process for that.
What can add more value to a glossary?
In conclusion, to create a good glossary, stick to the following rules:
- Significance. Don’t include business terms that may be familiar to the large part of application users.
- Conciseness. Don’t write a long article to explain the term, but provide general knowledge about it.
- Arrangement. Sort the list of terms in alphabetical order.
- Navigation. If the glossary is large, think about how to improve the navigation. For example, you can add page headers with variables that contain the first and the last terms on the page.
- Formatting. Make the glossary consistent and easy-to-scan. The size of heading letters and terms, paddings and white spaces is especially important.
- Presentation. If you deliver online documentation, consider making a glossary more user-friendly. For example, in MadCap Flare, you can configure your project to display the glossary terms as pop-up text.
The process of creating a glossary and writing the definitions is time-consuming. To use your time more effectively, try to create the glossary in the process of document development, not afterwards.
Most modern authoring tools offer advanced features to make glossary management easy. For example, in MadCap Flare, you can mark the needed words as Glossary Term Links. The terms are stored in a separate file, and you can add their definitions whenever necessary.
Anything that we missed? Let us know in comments!