Building a Glossary and Checking Terminology in Confluence
Comment
Building a Glossary and Checking Terminology in Confluence
What would you call the image below? A ‘drop-down list’? A ‘pull-down’ or ‘select list’? A ‘drop-box’?
I recently discussed this very issue with one of our Atlassian consultants. It seems everyone – from customers to consultants, developers and tech writers – has their own name for this UI element. We constantly refer to it in meetings, specs and technical documentation, but often do so in different ways.
Consistent wording is key to delivering clear, readable documentation. But when larger groups of authors collaborate to write documentation, they tend to use different words for the same things – such as jargon, or incorrect or obsolete terms. This is where terminology management comes to the rescue.
This blog post describes how you can build a glossary in Confluence to ensure terminology consistency. What’s more, I’ll show you a way to check your Confluence content for terminology and writing style.
Building a Glossary in Confluence
A glossary is an alphabetical list of terms and their corresponding definitions. It familiarizes readers with key words and abbreviations. Building a glossary is also the first step to truly consistent wording – and it increases understanding, too. This is often referred to as ‘terminology management’.
Confluence is the perfect place to create and manage a glossary centrally. Everyone within your organization, plus customers, partners etc. can enjoy access to this source of information – and could potentially contribute their own terms and definitions.
A Simple Glossary in Confluence
A typical approach to glossary building in Confluence is to create a page that contains a list or table of terms and their definitions. We did this for one of our app's documentation. Using the Expando macro, you can choose to display definitions collapsed by default to make scanning simple. Alternatively, the MultiExcerpt app lets you pull together multiple definitions in a single view.
For larger glossaries, we recommend creating a page for each term, and summarizing the glossary entries using, for example, the built-in Children Display macro or the Content by Label macro, in combination with the Excerpt macro:
Advanced Features Using the Glossary Blueprint
If you’d prefer an out-of-the-box Confluence glossary solution, you could try the Glossary plugin from the Atlassian Marketplace. It provides some really useful blueprints to help you create an extensive glossary. It also includes a clear, card-based overview layout for easy browsing and access to terms:
Terms and definitions are organized on pages for each letter (A-Z, plus optional custom pages for additional characters or symbols, e.g. 'Ä').
You can add entries to the glossary with point-and-click simplicity. Just select a word on a Confluence page, and then click the book icon in the context menu.
After saving, you can modify the glossary entry as and when required, and add rich-text formatting and media to your definition. It’s also possible to assign subject labels to each term, but it seems these app-specific labels currently have no other purpose, e.g. for navigation or grouping.
Your readers will be able to access the glossary’s contents in a matter of clicks.
- On any Confluence page, click the book icon above the page title. Please note, in the Documentation theme, this icon can be found in the "Tools" menu.
- All glossary terms on the Confluence page will be highlighted automatically.
- Click on a highlighted word, and the corresponding rich-formatted glossary definition will pop up
Checking Terminology Issues Inside Confluence – with Scroll Acrolinx Connector
When you need to manage terminology in a single language, a glossary is a great place to start. But many organizations need to juggle large volumes of content maintained by multiple authors, for diverse purposes, and in multiple languages. Their goal is to enhance overall language quality and cut translation costs significantly. And as a result, they take a more automated approach to ensuring consistent wording, correct spelling and grammar.
These organizations often manage terminology and other wording rules using an external (non-Confluence) platform.
The Acrolinx Language Optimization Platform
The Acrolinx content optimization platform is probably the most sophisticated system for terminology management, and for enforcing consistent wording across departments, teams and product lines. It provides a multilingual terminology database where preferred terms, alternatives, and forbidden variants can be defined with ease.
The solution’s key highlight is that the platform allows authors, editors and casual contributors to check their content for wording and grammar errors, in a similar way to spell-checking in word processors. In just a few clicks, users can resolve typos and wording inconsistencies, plus style guide violations where a specific voice or tone is required.
Automated Terminology and Style Checks in Confluence
To allow Confluence authors to run Acrolinx language checks on their pages, you can integrate Acrolinx’s language optimization functionality into your Atlassian collaboration platform and wiki.
If you choose to manage a glossary in Confluence, or to host a terminology database on an external platform such as Acrolinx, you will greatly enhance readers’ understanding of your key words and phrases. Terminology management helps us find and establish a common language – it could even help solve the initial ‘pull-down’ vs. ‘drop-box’ confusion that inspired this post.
If you're interested in accessing Acrolinx's language optimization directly in your Confluence instance, reach out to our team.
How do you manage your corporate terminology, and how do you ensure consistent language throughout your content? Do you want to embrace a more collaborative approach using Atlassian Confluence?
Please leave a comment below, or drop us an email at hello@k15t.com.
