Confluence Macros
Macros are a great way to improve the look, feel and functionality of a page or blog post.
Confluence pages go beyond just letting you put text on a page. While having text on a page is a very important aspect of the system, if that was all you could do, you would be very limited in your capabilities. Fortunately, the nice people at Atlassian have put in a number of widgets called Macros that help you extend the functionality of pages and save you a bunch of headache.
Macros are by no means necessary when using Confluence, however, they do make a number of things much easier. For example they can:
Automatically create a table of contents that updates based on headers on the page.
Pull in excerpts from pages with specific labels
Add a search box scoped to a specific part of the page hierarchy
Insert Jira tickets based on specific JQL
And a lot more
I find myself using macros on almost every page (and template) that I use, so let’s take a look at some of my favorites, as well as how you can find, and use macros.
Where are they found?
Macros are found on Pages and Blogs in Confluence. You can either click on the “+” menu in the toolbar, or use the “/” (forward slash) command to bring up a list of macros when you’re on a page or a blog.
From here, you can either scroll through the list, or search for the macro you want to use. I always encourage folks to take a look at the list of macros just to see what’s available. You should also note that different marketplace apps will add new macros. This means the list you see at one organization may not match that from anothers (this is a common source of confusion as folks think the same macros exist across all of Confluence).
Who can use macros?
Anyone who can edit a page or a blog can access macros. They’ll have full access to every macro that is installed, so there’s no additional management needed to provision or control them.
Individuals who have view access to a page or blog will see the macros, although unless they have edit access they won’t be able to edit them. It is important to remember that macros can pull in information from other pages - including ones a viewer doesn’t have access to. In this case the macro will display an error message to individuals who don’t have sufficient access. This is a common source of frustration as folks assume “Confluence is broken”. Here, a little bit of education can go a long way! (e.g. reach out for help instead of assuming something broke).
My Favorite Macros
Below are some of my favorite macros. This is by no means a definitive list of the “best” macros, just a list of ones that I find myself using on a regular basis.
Table of Contents
This macros automatically inserts a linked table of contents onto your page or blog. It bases the options based on headers in the document, and will automatically nest them so higher number headers appear under lower number ones.
This is a favorite of mine since it saves a ton of time having to manually insert a table of contents, and as long as I keep the headers updated it will update itself. It does have a few features that make it even more useful:
Include or exclude specific headers - You can choose to exclude headers below a certain size (e.g. only show headers 2 and higher), or even use regex to exclude headers that match a specific pattern. I commonly use this to exclude a “table of contents” header (one I frequently have on the page) as it doesn’t make sense to include that in the actual table of contents.
Horizontal orientation - The default layout for a table of contents is vertical, but you can also make it horizontal. I find this useful when I have a table of contents near the top of a page and think it looks better to have it go right to left.
There is a related macro called Table of Contents zone. This creates a table of contents based on a specific area of the page or blog. This is useful for creating “sub”-tables of contents, or providing more structure within a bigger piece of content.
Create from Template
This macros adds a button to your content that lets you create a new page from a selected macro with a single click. I find this incredibly useful for quickly creating pages for things I do frequently. Examples of this include things like meeting notes, team updates and the like. This is also a great feature to add for folks that infrequently use Confluence - instead of having to find the Templates menu they can just click a single button.
There aren’t many settings on this macro - basically you just select the template to use, and set a default page name. Despite being simple, however, it is an incredibly useful macro as it speeds up content creation and reduces the distance from “I want to create something” to “here’s my page”.
Panel Macros
Confluence doesn’t offer much in the way of visual formatting (at least without add ons!), so I frequently find myself using the “panel” macro to get some color on the page. This macros inserts a coloured box that can optionally include an emoji. I generally use this to draw attention to specific parts of a page (e.g. a “danger!”, “caution” or “Did you know?” box).
This is a very simple, but effective, macro, and only really offers a few options:
Color - The color you want to make the box
Emoji - Which emoji - if any - you want to include
This macro is another example of “simple doesn’t mean not useful”. Adding panels in appropriate spots (e.g. to call attention to specific pieces of information or warn about possible dangers) greatly improves the usability of pages and blogs.
Excerpt
Excerpt defines an area of the screen that can be pulled in by another macro. Excerpt by itself doesn’t do too much - just put a box on the screen - but when used in conjunction with other macros, like Excerpt Include, or Filter by Label - it’s very useful. I’ve found this useful in a number of different ways:
High level step-by-step - For longer process guides I commonly put an excerpt containing a brief overview of the steps. This excerpt is then pulled onto other pages, giving my team an idea of what the page is without having to open it.
Overview - Similar to #1 I’ll add an overview to pages in an Excerpt. This allows me to pull in the overviews across other pages, letting folks know what’s in store for them on the page.
Critical information - For longer pages I’ll put critical bits of information in excerpts. This lets me easily pull that information onto other pages, without having to maintain it in multiple spots.
Conclusion
There are a lot of different macros available out of the box, and many, many more available via marketplace add ons. Take time to explore the ones you have as many of them will make your life a lot easier.
The Importance of Ticket Deflection
Answering tickets is great - but preventing the need for them is even better.
Any given support team will collect a large amount of tickets. These can range in complexity from simple to complex, and require a wide range of skill sets to manage, track and resolve.
The first step in handling those tickets is to gather them all in one spot with a tool like Zendesk, Jira, Asana or something else. This allows groups to track their status, report on them and manage the workload. Generally a small group (sometimes just one person!) handles all the tickets.
Eventually, however, the number of tickets and the types of tickets that come in begins to grow. That small team will find itself buried under a landslide of requests, and will be rapidly shifting from one type of ticket to another. This constant pressure, and need to context switch takes its toll.
Tiered Approach
To help address the wide range of tickets that come in, companies tend to evolve a multi-tiered approach for their support teams to handle the influx:
Tier 1 - This is the front line and is equipped with stock responses to as many tickets as possible. They’re typically trained how to triage any given ticket, and if they have a response to provide it. Examples of tickets this group can handle are things like password resets, simple Q&A and general feedback.
Tier 2 - This is a more specialized group that takes over any ticket that Tier 1 isn’t equipped to handle. They may have some stock responses, but generally this tier has either access or training that the Tier 1 group lacks. There are, however, some things Tier 2 can’t handle.
Tier 3 - These are your super-experts and they handle the most complex or challenging topics. Ideally only a small percentage of tickets end up in this group as there tend to not be many of them, and the requests can take a while to respond.
This structure allows the team to specialize. Some agents tackle the large numbers of “simple” tickets, while a smaller number focus on the “complex” ones. This increases response times, as well as satisfaction, as the simple ones are knocked out more quickly, while a more knowledgeable agent handles the harder ones.
This approach, however, requires humans - someone who is trained in how to respond to, and resolve, issues. In many cases a human is required to help out, however, employing someone to answer tickets can be expensive, and it can result in it taking longer to get an answer.
The 0-eth Tier
This is where ticket deflection, or Tier 0, comes in. This tier is everything the customer can do BEFORE asking for help. It could involve reading a wiki page, asking a chatbot something, or trying it themselves. There’s a wide range of things this COULD be, but they all result in the customer getting an answer/help without having to interact with someone on a support team.
Examples include:
A knowledge base - Having robust, customer-facing documentation is a great way to empower customers to answer their own questions. These do take time to setup and maintain, however, directing customers to them is significantly cheaper than having a human answer at ticket. Many customers also want the ability to lookup information on their own, so having a knowledge base available also helps fill that need.
In addition to questions and answers, knowledge bases can also contain step-by-step guides customers can try on their own to resolve their issues. This subset of information gives customers one more thing they can do before having to interact with your support team. This allows customers to get help 24/7, and further reduces the demands on your support desk.
Chat bots - Chat bots are getting a LOT smarter and a lot more helpful. While there are certainly some gaps and features that aren’t quite there yet, these interactive tools make accessing information and guiding customers to responses a bit quicker than search. Some of the newer tools are even able to take action on behalf of a customer - for example resetting their password. This reduces the number of things your TIer 1 team is responsible for, both simplifying their workload but also reducing it.
Automated Tools - This one can be a bit trickier to setup, but having a tool the customer can use, without having to access a support team, is another way to deflect tickets. Resetting a password is a common example - customers click a button and go to their email to get back in. This shortens the distance between the customer having an issue and getting it solved.
Typically Tier 0 starts out as a small help-center, however, it should be constantly evaluated, expanded and updated as time goes on. Not only will older content need to be refreshed, but new pages, tools and guides can be added.
Tier 0 Improvements
Agents should be constantly on the lookout for opportunities to improve Tier 0. Not only do they see all the incoming requests, but they have solutions for them. There’s several ways this can be done:
Writing (or rewriting) articles - Agents are typically closest to the problems, and solutions, so they should either have the ability to directly edit or update articles, or have a process to suggest changes.
Product improvements - Agents should have a pathway to suggest product changes to avoid the need for a ticket. These suggestions should be reviewed by product, marketing, or other teams, to see what can be incorporated to help alleviate the need for a ticket.
Training materials - Agents should suggest ways to train customers or users on how to use systems. This can directly reduce the number of “how do I do X” tickets.
Deflection can be a bit tricky to quantify, after all you’re stopping them from having to do something (put in a ticket), so you may never know how much it’s REALLY impacting. There are a few ways to keep an eye on it.
Knowledge base utilization - Tracking which pages are used can give you insight into how much pressure it’s taking off your ticketing system. For example if you add a new article on password resets and that ticket type drops, you can infer the article had some impact.
Automated actions - The number of times your chatbot (or other tool) takes actions is another way to see how effective it is. Each password reset done automatically is essentially a ticket that wasn’t submitted.
Ticket deflection is incredibly important to a successful ticketing system. Not only does it reduce pressure on your support teams by both reducing volume and the number of things they have to handle, it empowers customers to take action… and is faster than putting in a ticket. There is a bit of legwork needed to determine what can be done, but it’s more than worth it.
The importance of Header Styles
I’ve (finally) figured out that formatting is an important part of a wiki. Shockingly folks don’t appreciate reading giant walls of text, so understanding how to break up a page in a way that improves it’s usefulness is important. One way we do this is with headers.
Headers are useful in breaking up the page into discrete sections. I think of them like chapters in a book - they signal to the reader what is coming up, and let folks skip around to more interesting sections if they like.
A VERY common way to do this is simply by changing the size of the text, or by bolding it.
While this DOES make the text bigger and bolder, it can rob you of some interesting features built into knowledge systems.
Header Styles
Instead, use header styles, NOT font sizing, to break up pages into sections. Header styles will also break up the page with clear headers, but have a major advantage over bolding and font sizing - they interact with the tool in different ways.
In Confluence
Using header styles in Confluence lets you do some pretty cool things like:
1️⃣ - Automatically generate a table of contents - The Table of Contents (TOC) macro will generate a TOC based on headers on the page. Easy!
2️⃣ - Send a hyperlink directly to that specific header - each Header will have it's own link, letting you send folks directly to it.
3️⃣ - Easily standardize look and feel - Using header styles will ensure your headers always look the same between pages.
Click the text size drop down & select your size
Type it in!
In Google Docs
Header styles in Google Docs let you easily create a table of contents and link to headers
Select the header size
Type it in
Google automagically makes a table of contents
Label Management in Confluence
Labels are a great way to help manage content, but tend to spiral out of control as anyone can add a new label to a page. This results in a large number of similar, or unneeded, labels, which clutter your system and make it harder to manage.
Why label management is important
Over time your system will collect more and more labels. Many of these will likely be legitimate labels used to help manager your knowledge base. Over time, however, you will start to collect typos, deprecated (un-needed) and duplicate labels.
Common examples include:
Plural vs Singular - “benefits” and “benefit”
Typos - “beneift” not “benefit”
Unneeded - “Excel” (but you no longer use or need this)
At best these labels clutter up the screen when selecting new labels - at worst users add them to documents which will confuse and break your search and other features.
A Solution
Setting up a regular label review (similar to a content review) will help you manage and update your labels. There are two macros that will help you
Labels List - Gives you all the labels in a specific space in alphabetical order
Popular Labels - Displays all labels in a specific space sized by use
Labels List
A-O
P-Z
0-9
This is useful for quickly seeing how many labels there are, and if there are any potential duplicates / un-needed labels. Click on the label to see a list of pages with that label.
Popular Labels
Generates either a list of labels or a heatmap. The list will display labels in descending order of use (most used at the top), while the heat-map displays them alphabetically and changes the size based on use (most used is bigger).