Here’s the scenario: You’re writing a Confluence page and you want to include additional context, provide explanation or guide users through your content. What would you do? Although there are a host of macros that more or less help you contextualize your content, one stands out: A typical Confluence tooltip.
In this article, we will see why you need confluence tooltips, when to include them, and of course, the best practices to make the most out of them.
Why do you need a Confluence tooltip?
Tooltips are primarily designed to provide context and help readers easily navigate your content. Although straightforward in theory, we’ve seen many use tooltips for a host of various use cases. Here are the most popular ones:
- Defining terms:
Your content might be filled with technical terms and acronyms that your readers might not be familiar with. Tooltips are great to add instant definitions helping users get the information they need without having to leave the page.
- Guiding User Actions:
We’ve all used apps that guided us through tooltips. If your content is pretty much straightforward, you won’t be needing this. But for long pieces of content, you might consider tooltips to guide users through your content. For example, you can offer hints or instructions next to buttons, links, or interactive elements.
- Adding supplementary context:
When writing a piece of content, you have to prioritize the information you want to display. Otherwise, your page will be cluttered, hindering navigation. For example, if you feel that a specific sentence needs further explanation that not all readers want to further explore, you might use a tooltip. Hovering over the section will display the additional information.
- Explaining Visuals or Images:
Provide additional details about diagrams, screenshots, or infographics, such as explaining a process flow or highlighting key elements.
Is there a native tooltip macro in Confluence?
For the time being, Confluence doesn’t offer a tooltip macro. Why? Your guess is as good as mine. And based on the current roadmap, it doesn’t look like the feature will be introduced anytime soon.
But when it comes to Confluence, there is always a workaround. The question is whether they’re good enough to act as a tooltip. The answer is simple: Not really. If you need a tooltip within your content, just insert one.
That said, if you’re exploring alternatives, let’s break down some commonly suggested options:
- Inline Comments: A Temporary Fix, but Not Scalable for Polished Content
Inline comments are designed for collaboration, not for additional context to readers. Using them as tooltips blurs their intended purpose, making genuine comments less noticeable.
- Panels: Great for Context but Too Visually Prominent
Panels are designed to make content stand out, which is excellent for drawing attention to important information (think pro tips, warnings, etc). The issue here is that panels take much more space compared to tooltips and can’t be linked to specific terms or sentences. This applies to both native Confluence panels or third party ones.
- Footnotes: A Solid Choice for Citations but Clunky for Simple Explanations
Footnotes are great to cite sources and references. But using them as a substitute to tooltips is a step too far for two reasons: Navigation and immediacy. An actual tooltip offers instant access to information, while a footnote requires the user to scroll to the bottom of the page to find the reference. This further complicates navigation, and of course, engagement with your content.
Best practices to implement tooltips in Confluence
Keep it short and simple
Tooltips are meant to be helpful, and to the point. Keep the text concise—think one or two lines that give just enough context or clarity. No one wants to hover over a word only to be met with a wall of text. In case you have more context to provide, you might think of other alternatives such as a link to a specific page or expanders.
Context first
A tooltip works best when it answers the immediate question a reader might have. What does this acronym mean? Which section should I explore next? And more. Avoid generic messages or using tooltips only to put links within them. Instead, be precise and add value. For instance, “Requires admin privileges to access settings” is way more helpful.
Be consistent
Tooltips work best when used thoughtfully and consistently. And for this you need to find the perfect balance. But how? Say you’re navigating a Confluence page only to find a tooltip for every other word. It’s safe to say, you’ll feel overwhelmed and you’ll end up ignoring the majority of them. To strike the perfect balance you need to prioritize and only add tooltips when you know you’ve used a new term, provided an update, etc.
For more content formatting tip, make sure to check out this dedicated blog.
How to add tooltips in Confluence
The tooltip macro is available within our Content Formatting Toolkit for both Confluence Cloud and Data Center. Using the tooltip macro is simple.
- First, navigate to your Confluence page and hit edit.
- Select the area where you want to add a tooltip. It can be in the middle or the end of a sentence. Type Tooltip | Vectors. Specify the term or sentence you want to provide more context to.
- Add the tooltip description. Of course, bearing in mind the best practices we’ve mentioned above.
- Select a color if you want to further customize your tooltip and make it stand out.
- Once you finish, hit “Save” and then “Update”.
Tooltips are ideal to facilitate navigation, improve clarity, and overall user experience in Confluence. From explaining specific terms and acronyms to offering quick guidance, they’re your go-to for delivering context without overwhelming your pages. While Confluence doesn’t have a native tooltip feature (for the time being at least), our tooltip macro steps in to fill the gap seamlessly.
If you’d like to further enhance your Confluence content and feel native macros don’t quite cut it for you, make sure to give the tooltip macro a try. And for more posts like this one, check out our blog.
