How to Highlight Glossary Terms within Confluence Pages (+ Pro Tips)

[#1]

When it comes to Confluence glossaries, convenience and context are key. You shouldn't expect your users to access your glossary every time they encounter a term they don’t understand or they want more in depth info. This is where highlights come into play. They allow you to give quick explanations without breaking the reader’s flow.

In this post, we’ll explore the new enhanced highlight engine for glossary, why it matters, and compare some options.

Why highlights? 

Easy access: 

Imagine a Confluence page filled with technical jargon. With no highlights, your users will have to constantly go back and forth between the pages and the glossary or ask their peers. This loses them valuable time and results in an overall bad reading experience.

Scalability & maintenance:

Let's say you have the term “Scrum” present in 20 Confluence pages. With no highlights, you need to manually add the definition within each page. Every time you want to update the term, you need to go through all pages again. That’s a significant effort easily avoided with highlights. Every time a term is updated, it will automatically show within all Confluence pages where it resides, saving valuable time and reducing errors.

Some alternatives to highlights (and their limitations)

Tooltips: Provide quick definitions, but they’re not stored anywhere in Confluence

At first glance, one might argue that tooltips are perfect to highlight key terms and definitions within a Confluence page. In a way it’s true. Your readers get the definition without breaking the flow.

Now what if you want to highlight the same term across multiple pages? This is when the limitation appears. Tooltips are not tied to a central glossary which requires you to manually change each one. + if readers want to learn more about each term, tooltips don’t act as a gateway for more context or metadata.

Links: Direct access to glossaries, but not inline

Now the issue with tooltips is that they’re not tied to a glossary entry, but links are. They can take readers straight to the term source. This means for every term, one has to jump into the glossary, and then navigate back to continue reading. Not particularly ideal.

On top of that, linking terms is as manual as it gets. You have to decide which terms deserve links, insert them one by one on every page. What happens when someone needs the definition of a term you didn’t think was important enough to link? They’re stuck searching on their own.

Macros: Embed terms, still not inline

At first, macros might look like a solid option to highlight existing terms within a Confluence page. They let you display definitions in a more structured way, lists or tables. But here’s the catch. Although quite convenient, they're not inline regardless of where they’re placed. You want terms to be accessible exactly where they appear, not buried in a block further down the section or a page.

Atlassian Intelligence: No required setup, but a double-edged sword

Atlassian Intelligence makes it easy to get quick definitions on the fly. Just highlight a term within a Confluence page, click Define, and you’ll instantly see a definition along with the source it was pulled from. 

But that zero setup is also a double-edged sword. Since there’s no glossary behind it, terms aren’t stored anywhere for future use or more in-depth details. But I can access the source one might argue. In my own testing environment, where I didn’t have many pages, the AI often tied definitions back to the space homepage whenever a similar term existed. The result was a generic definition that didn’t really fit the way I needed to use the term.

How to highlight glossary terms across Confluence pages

• Within your Confluence page, hit the glossary highlight icon.
• All terms will be highlighted and listed on the right hand side of the view. 

• With this new release, we offered highlight configuration options not only for admins at a space level, but regular users at a page level. You can specify what to highlight (only terms or abbreviations and synonyms), precision (partial or exact), and frequency (first match, all, etc).

Best Practices to make the most out of glossary highlights

What to highlight: don’t forget abbreviations and synonyms

More often than not, the term wouldn’t be present within a Confluence page, but its abbreviation or synonym are. Some examples that might come to mind are SEO, SEM, etc. Here, within the highlights configuration, always include metadata so your readers won’t miss important terms.

Frequency: find the right balance

If the term Scrum is repeated 10 times within a page, it doesn’t make sense to highlight it as many times. This will create an overwhelming experience for the reader and might make them miss other terms. Instead opt to highlight once or just a handful of times if the page is long.

Precision: watch out for unintended matches

Some terms might be part of other larger ones. If within your glossary, you’ve defined the term User, other terms such as Username, UserID will be highlighted. And this is when you can opt for exact matches. Use them to avoid these accidental highlights, and partial matches only if you’re confident it won’t create confusion.

Keep your glossary updated

This one is obvious. Your highlights are as good as your glossary. If your terms and definitions are outdated, you’re not bringing any value. Make sure to continuously update your glossary entries and invite your users to suggest changes.

Having the glossary highlight feature will definitely make life easier for those managing glossaries, and the ones accessing them. Our new enhanced highlights engine is available now with our latest release. Make sure to give it a try here.