What makes a good glossary in Confluence? And how you can create your own
Glossaries in an excel sheet are perhaps the most 90s thing you can see in 2024. They are long, look necessarily complex and are a nightmare to navigate through for a myopic like me. You can see where this is going, glossaries shouldn’t be managed this way! So the question here is: what makes a good glossary in Confluence?
In this article I will share a couple of tips and best practices to help you better create, centralize and manage glossaries inside Confluence.
A good glossary is organized and well-structured
Glossaries are all about structure and organization. At the end of the day, they are here to replace constant toggling between spreadsheets and apps. So make sure to structure your glossary in a way that makes it easier for your teams to access terms and definitions. For this you can leverage native Confluence features such as page trees coupled with the “Content glossary design” page template. This is a good place to start, but what if you want a centralized and pre-structured glossary hub not only pages? Well, there is an app for that.
Glossary for Confluence comes with a variety of views designed to make glossary creation a simple yet intuitive process. At the core of the app, you have the glossary main dashboard. This is where you find all terms created (be it within a given space, or your entire Confluence site). It is just a matter of where did you access the dashboard.
Then, you have a host of sections, three in total: terms, languages and labels. The three are pretty much self explanatory. The terms section contains all terms created within a given space or Confluence site. The languages section classifies glossaries by language, and finally the labels section gives you access to terms based on the labels they are associated with.
A good glossary is managed by key contributors
Although AI has taken over a lot of manual tasks including glossary creation and management in some other platforms, the human touch remains crucially important especially in the management part.
Good and comprehensive glossaries often require constant collaboration and input from key contributors. Make sure to Identify the ones with the required expertise and knowledge of the terminology relevant to your business, specific projects and industry. Grant these contributors appropriate permissions to conduct research, contribute to the glossary, ensuring that it remains comprehensive and accurate over time.
A good glossary is filled with metadata and labels
Glossaries are created to contextualize content and promote a shared understanding. Enhance the usability of your glossary by enriching each term with relevant metadata. This could include synonyms, abbreviations, attachments, and labels. The latter provide additional context and aid in categorization and classification.
Additionally the dedicated labels view available within the glossary space/site dashboard and glossary view, allow your teams to group terms under the same label, further facilitating the search process.
A good glossary is easily created from anywhere in Confluence
The straightforward way to fill your glossaries is to access them and create terms there. But should it be the only way? The answer is no. Terms should be easily added from anywhere inside Confluence. And for this, Glossary for Confluence comes with the inline feature allowing key contributors to add terms and definitions on the go. All they have to do is select the term in question and fill in the required fields including the definition and metadata, and of course, select the right glossary and space.
A good glossary is accessible with highlights
Similar to creating terms, accessing them shouldn’t only happen from within the glossary itself, but rather anywhere in Confluence. And for this the highlight feature comes in handy in helping your teams quickly grasp definitions.
From within every Confluence page, there is the glossary highlight button. Once clicked, it highlights and organizes all the terms within the Confluence page. From there, you can expand or collapse terms, quickly scan definitions, and navigate to the full glossary entries if needed.
As a regular user not only an admin, you can define the highlight behavior by specifying what to highlight, precision, and frequency.
A good glossary is multilingual and contains translations
For multilingual teams, glossaries play an important role in keeping everyone aligned through detailed and accurate terminology. However, many teams often create one glossary per language. Nothing wrong with that if we’re talking two to three languages max. More? and you might end up with too many glossaries which obviously makes navigation more complex, and maintenance a nightmare.
With Translation, you can maintain one single source of truth in one single language. Simply create a master term, then add translations underneath. This keeps terminology consistent across languages, reduces duplication, and makes updates much simpler.
A good glossary comes with tailored macros & is easy to embed within Confluence pages
Although you can make your glossary easy to access with highlights, at times you want to put forward specific terms within Confluence pages. And for this you’d obviously use macros. The latest release of the glossary app comes with two brand new macros: Term list & cards.
The term list macro allows you to embed terms mentioned within a page, or specific ones from a chosen glossary. They’re perfect within content-rich pages filled with a variety of terms such as documentation, onboarding guides, etc.
The term card, on the other hand, puts forward only one term along with its definition, translations (if either any), metadata, and a quick link to the source glossary. You’d want to use it to provide more context at the end of each section.
A good glossary is searchable and easily located
You can access terms by navigating the glossary, by highlighting terms in Confluence pages, and by search. And the latter is rooted in every app we use, for one simple reason: Convenience. If I am looking for a specific term, I can simply hit that search bar. And the good news is that glossaries, whether created with native Confluence templates or leveraging apps like Glossary for Confluence are deeply integrated with Confluence search.
For example, if you have the app installed in your Confluence site, you can enter your search query, then select Confluence Advanced search, and filter your search results based on various search types including: glossary, term and letter. This saves your users time and helps them quickly find the terms they are looking for. In addition, the app comes with its own search engine integrated within every view. This is particularly useful for users who know the view where they should look, make the search more tagged and time efficient.
A good glossary is easily imported and exported
Many teams ask the same question when getting started with glossaries in Confluence: What about all the glossaries I already have outside of Confluence, and will it be easy to import them? The answer is yes. If you already have your glossaries created, it doesn’t make sense to create them again from scratch. Glossary for Confluence comes with an import/export feature allowing you to easily import and export your glossaries in different file formats including CSV, JSON and PDF.
A good glossary is relevant over time
Finally, keep your glossary up-to-date and relevant to the needs of your teams. Make sure to regularly review and update terms, definitions and metadata to reflect changes in terminology, practices at both corporate and team levels, etc. To further make this process efficient, encourage feedback from both your key contributors and users. This will help in identifying outdated content, duplicated terms across spaces, and generally enrich your glossary hub.
Creating a good and content-rich glossaries in Confluence requires careful planning, constant collaboration, and the right tools. In your opinion what makes a good glossary in Confluence? Tell us what you think in the comments below. And if you like to get started with Glossaries, then make sure to give Glossary for Confluence a try here.
Was this helpful?
Thanks!
Fares Laroui_Vectors_
2 comments