What is scripting?

Quick note! This blog post is sponsored by my friends over at ScriptRunner.

When I first got into systems I heard a lot about scripting. For a long time, it was a mystery to me. I never saw anything called ‘scripting’ in the system but the administrators (‘admins’) were always talking about it. Then it got even more confusing after an admin showed me a script, which, to me, looked like highly complex code. Fortunately, he also told me something that really helped me out - it's just instructions telling the computer how to automate a task.

That’s all scripting is - a set of instructions a computer understands that guide it along a process. The process can be simple - add a label when a ticket is created, or complex - copy a range of tickets to a new release when a specific condition is met.   A big thing to remember is the computer only does what we tell it to in the script, it can't make a judgment call or change its mind like a human can. Instead, it performs the actions we describe literally, which means we have to be careful when we consider what we want a script to do.

What can scripts do?

Since that day an admin showed me scripting I've used it to automate a wide range of tasks, including things like: 

1. Surveying thousands of managers about where their team works from

2. Streamlining a recruiting system by automatically generating offer letters

3. Reduced the number of manual steps necessary to update new hire records

4. Email me when a system experiences an error or needs help

5. Sample tickets an agent has solved and send a form to a quality analyst to rate their work, then send those results to the agent manager

Other than my technical knowledge of what's possible and my imagination, I've learned that there aren't many limits to scripting. This makes it both really hard and really easy to think of things I want to script out. It's hard because I need to keep learning more about scripting, how to do it and understand limits, and easy because if I can dream it I can (usually) script it.

Why is scripting useful?

Scripting’s biggest offering is something called extensibility - the ability to expand what a system can do. Typically a system will come with a set amount of features tailored to most use cases. Unfortunately, those features rarely meet every need you might have, which is where scripting comes in. 

Scripts offer the opportunity to build new features to meet your needs or to modify existing ones to do things differently. For me, this is an amazing feature, since it allows me to take an existing system that does, say 90% of what I need, and get it to cover 100% (or closer to 100%!) of my needs.

I’ve worked with a lot of teams that suffered by using the system’s default feature. They figured ‘that's just how it is’ and assumed they were stuck with it. Scripting, however, offers you a way to have the system perform a task exactly to your needs. Instead of suffering with a ‘it mostly works’ feature, scripting lets you tailor it to your needs.

How does Jira - and ScriptRunner -  support scripting?

The coding language used to create Jira is called Java, and while the nice people at Atlassian have made it possible to write custom plugins in Java via a set of APIs (Application Programmer Interfaces), that is an incredibly complex endeavor. To help simplify things, ScriptRunner uses a scripting language called Groovy to allow admins to more easily work with Jira.

That sounds like a lot of information, but don't worry too much if you don't know what that means. The biggest takeaway is that if you want to automate something in Jira with scripting, you'll need to get Groovy (get it?). Groovy also happens to be what ScriptRunner is built on, so if you have ScriptRunner you still need to get groovy.

(I'll dig more into ScriptRunner and a new, HAPI-er, way to script in the next post)

What should you know about scripting?

There is however, more to scripting than just knowing the language or knowing specific commands. For me, scripting begins when I realize I perform the same thing over and over. When I catch myself repeating the same task (always assigning a specific ticket type to one group, always pushing a release after a specific approval, etc) I ask myself if it's something I could automate.

Making time to identify and think through possible things to automate is a critical step. Many teams rush into automating, only to realize they missed a critical use case or picked an overly complex one. Taking time to consider what should be automated helps avoid those challenges.

Personally, I keep a running list of things I'm thinking of automating. I then make time to review it with my team and pick the highest priority, or lowest lift, ideas. Once we’ve had time to review the list, we pick one or two and then go about planning out what I need to do to make the script work.

This typically takes the form of clearly defining the objective, for example, assigning a ticket to a specific person if it's a specific type, and then listing all the steps needed to do that. For example:

1. The ticket is created as a ‘bug’ or changed to the ‘bug type

2. Changed the ‘assignee’ to ‘rob’

3. Add this comment and @ mention Rob ‘new bug for you!’

4. Add the bug to Rob’s Kanban board

My goal is to write the steps down so anyone can follow them and get to the right end result. I do this because that is how the script will run - following each step literally - so if a human with no background knowledge can follow it, I'm ready to script.

That is a very simple example, but many scripts will handle much more complex situations. Many times I find myself having to get creative in terms of how I think of the problem. There could be technical limitations to the process - maybe I can't quickly convert all the subtasks to epics - that force me to try something new. Alternatively I may have to consider changing the underlying process to fit into how I can script the solution. Either challenge requires me to get a bit creative in my solution.

Scripting as problem-solving

There is another soft skill I constantly apply when I build scripts - problem solving. This can crop up anywhere, from a bug in my code, to a lack of knowledge about how to script, to an issue with the underlying process. Scripting has taught me to be on the lookout for challenges and to become flexible in how I solve them.

Frequently I’m applying problem solving when I run into a bug somewhere in my script. Many scripting languages are complex, making it very easy to make a mistake (even if you’re an expert!). This commonly results in a lot of time spent debugging (looking for the error). Personally I find this to be an excellent learning experience as I get to dig deep into the issue. Many folks, however, would much rather focus their energy on solving their business challenge - not fighting with a scripting language.

I’ll get more into a HAPI-er way to script in the next post - but keep in mind a large portion of scripting is finding, and solving, problems… not knowing a specific language or technology.

Conclusion

Scripting is a powerful tool that lets us extend what systems are capable of. It not only allows us to add new features and abilities to systems, it lets us address unique challenges our organizations face. It can, however, be challenging to learn, and that can present a big barrier to entry.

Fortunately, there are solutions out there that help make this barrier (at least a bit) smaller. Check out my next post for a solution that will make Jira admins more than a bit HAPI-er… 

Although if you’re curious, you can try HAPI now

Confluence for Agile Teams

There's a common misconception that agile projects don't have any documentation. This is simply incorrect. Agile projects do have documentation, however, they aren't as focused on creating and maintaining it as a waterfall project might be. Agile teams may also have different requirements of their documentation system, for example needing it to integrate with ticketing, or provide faster ways to create information.

This means that agile teams still have a need for maintaining and sharing documentation. And given it's an agile project, whatever solution they use should also be lightweight and tailored to their needs. Fortunately Confluence meets both these (and many other!) needs.

Confluence agility

When I think of agile documentation, I think of documentation that captures the bare minimum information needed to move the team forward or to meet the needs of the customer. This necessitates a platform that can be configured to accept the minimal amount of information a team decides to add, but also ensure it's easily accessible.
Confluence helps solve the “capture information quickly” requirement with templates. Templates allow content creators to quickly spin up new pages, and removes the need for them to consider things like formatting. By taking a few minutes at the start of a project an agile team can put together templates that speed up information capture, and also keep creators on track to ensure they're not over documenting. This helps ensure that teams can stay focused on providing value to customers - and not fighting to get columns aligned.

Templates offer some other features, like the ability to be pre-configured with labels, meaning they'll easily tie pages created from them back into search, macros and other features that make information organization and retrieval easy. While this benefits any type of project, it further supports Agile teams by automating the need to add those labels.

This isn't to say the team can't deviate from templates.  There will be occasions they'll need to go ‘off script’, however, Agile teams can likely think through the most commonly needed documents and template them out. Examples include:

1. Retrospectives

2. Sprint planning

3. Team updates

4. Sprint review 

5. Technical documentation 

Even better, Confluence comes preloaded with a number of these as blueprints. These make it even easier to get started since you can just use one off the shelf. That said, teams should take time to tailor the existing blueprints to meet their needs.

Automations

There are many aspects of knowledge management that are highly mechanical. For example, archiving documents after a certain age, or alerting the team when new content is created. While a human could certainly perform these actions, it sucks up time and energy. Fortunately Confluence has an answer in the form of automations.

These are just rules you setup to enforce specific actions. For example, you might archive meeting notes after 3 months to ensure your space is free of clutter. Or you may alert the page owner when a page is attached to a Jira ticket. Or almost any other manual action you can think of.

This ability to automate away tasks makes automations incredibly valuable to agile teams, and is another great example of allowing the team to focus on building value and not fighting with systems.

Jira Integration

There are many aspects of knowledge management that are highly mechanical. For example, archiving documents after a certain age, or alerting the team when new content is created. While a human could certainly perform these actions, it sucks up time and energy. Fortunately Confluence has an answer in the form of automations.

These are just rules you setup to enforce specific actions. For example, you might archive meeting notes after 3 months to ensure your space is free of clutter. Or you may alert the page owner when a page is attached to a Jira ticket. Or almost any other manual action you can think of.

This ability to automate away tasks makes automations incredibly valuable to agile teams, and is another great example of allowing the team to focus on building value and not fighting with systems.

Jira Integration

If a team is using Confluence they're also likely using Jira to track their work. This gives agile teams even more options for simplifying their documentation as Jira and Confluence are highly integrated.

Typically I use this integration to pull tickets for upcoming sprints into Confluence pages, or to display tickets from the prior sprint in a review or retrospective. This helps streamline those meetings as we don't have to switch between systems when discussing our plans or reviewing our progress.

There are also some interesting things you can do with Confluence white boards. An upcoming feature will include ‘smart sections’.This allows teams to drag and drop tickets over a section and change a field on the Jira ticket.  For example, a team could have one section per team member, and just drag tickets over their section to assign them.

This is another example of speeding up the team by shifting where an action is needed.  Sure they could go into Jira and move tickets, but if they're already in Confluence planning the sprint, why not stay in Confluence?

Linking to tickets

Another way Confluence helps speed up teams is by linking Confluence pages directly to Jira tickets. This doesn't seem like much, however, it helps shorten the distance a team member has to go in order to get what they need.

For example, instead of having to go into Confluence to look up a specific page, a developer can click on a link on their ticket and see exactly what they need. This might only save a few minutes, but that adds up - both in terms of time and in terms of frustration - over the project.

I commonly find myself linking high-level project documents to tickets - things like product requirement documents, scope requirements etc. This helps ensure my team has instant access to contextual information that will help them make the best decisions possible when they begin work.

Structure

Confluence also offers a number of great options for storing information. For example, a team may have a new space for each project, and then archive the entire space when they’re done. This allows them to review information as needed to help improve future projects. Access can also be shared across an organization, allowing other teams to benefit from lessons learned by one team, further amplifying their value.

Teams have a wide range of options in terms of structuring information. This gives Agile teams the flexibility they need to create and store documentation, while still making it available to others. For example, one Agile team could choose to use a single space for all the information, while another uses different ones. This is fine, as Confluence will allow them to search and link between teams with issues.

Wrap

Every project will generate some amount of documentation, and it is important for teams, even Agile teams, to keep track of it all. Fortunately Confluence offers a number of different ways for Agile teams to do just that.

Atlassian Marketplace

Confluence comes with a lot of great features right out of the box. There are, however, use cases that it can’t quite match or very useful features that aren’t included. Fortunately, there’s a robust application (app) marketplace available which allows admins a lot of options in expanding what Confluence can do.

What is the App Marketplace?

The app marketplace (https://marketplace.atlassian.com/) is essentially a webstore for Atlassian products that allows developers a place to offer extensions. These range from simple UI changes, to in-depth product adjustments. Some are free, while others are paid. The marketplace itself is fairly well organized, making it easy for admins to quickly search and find things they’re looking for.

Like many app stores, users can rate their apps on a scale of 1-4. This rating gives admins a good feeling for how well an app could meet their needs. You can also see how many times a particular app has been installed, giving further confidence in it (or not!).

How do I find apps?

The marketplace has a built-in search feature, making it easy to look for apps. It is also organized into a wide range of categories (“administrative”, “project management”, “communication” and the like), giving admins an easy way to browse and see what’s in there.

Admins can also easily see which apps apply to specific products - for example getting a list of just apps that work with Confluence. This is another easy way for admins to browse what is available, or to just get ideas on what they might need.

How much does it cost?

All apps offer a free 30 day trial - regardless of your team’s size. This means you can test of any app for a month to see if it’s a good fit. On top of that, many apps also offer a free tier for groups under 10 users. This means that smaller organizations can benefit from many of these apps without having to pay anything.

For Confluence Cloud each app will have its own monthly and yearly pricing. Monthly pricing tends to be by the number of users you have, and will be slightly more expensive than if you purchase yearly. Yearly pricing tends to be broken out by tier (e.g. 51-100 users) and will just be a yearly charge instead of a monthly one.

If you’re on Data Center pricing is done on a yearly basis and pegged to user tiers (e.g. 101-200 users is $X, 201-500 is $Y).

What does subscribing include?

In addition to getting the app itself, subscribing will also include support for the app, as well as automatic updates. This means you’ll never be on an “old” version of an app (at least if you’re on Cloud!). Data Center versions of apps may require manual updates to ensure compatibility with your version of Data Center.

Wrap

While “stock” Confluence offers a lot of great features, there are many things it just doesn’t do - and this is where the marketplace steps in. It’s definitely worth taking time to browse and see what is available - you never know when you’ll find the tool that perfectly meets your needs.

Confluence Macros

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:

1. Automatically create a table of contents that updates based on headers on the page.

2. Pull in excerpts from pages with specific labels

3. Add a search box scoped to a specific part of the page hierarchy

4. Insert Jira tickets based on specific JQL

5. 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:

1. 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.

2. 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:

1. Color - The color you want to make the box

2. 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:

1. 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.

2. 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.

3. 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.

Confluence for Support Teams

Confluence helps serve a number of different roles for teams, and while mainly it’s used as a collaboration platform, it also helps fill a big need for Support teams - that of a knowledge base.

Source of truth

One of the most successful uses of Confluence I’ve seen was being the source of truth for an HR support team. This group was responsible for triaging 100,000+ tickets every year ranging in topics from onboarding to benefits to recruiting across dozens of countries. This made for a very large range of tickets that any given agent could end up handling, making training and onboarding very challenging.

The team had two dedicated individuals whose main job was to keep Confluence updated. They would constantly review documentation, tickets, feedback from folks and other information to ensure that every possible ticket the team might get was thoroughly documented. They included screenshots, escalation paths, background information and more all in one spot. This meant that any team member could easily look up a particular type of ticket and get everything they needed to answer it.

While not every team will have the luxury of dedicated knowledge managers, having a single place to store everything - especially one that is integrated with your ticketing system - makes resolving tickets much easier. Agents won’t waste time having to dig through different systems - everything is in one spot. I’ve seen teams benefit from this by rotating the responsibility of creating updates between agents. This spreads out the load (preventing the need for a dedicated headcount), but also gives each agent some experience building the knowledge base. This can be a great break from grinding through tickets, and also expose agents to other areas they may not have been exposed to before.

Standardization

Leveraging Confluence had the added benefit of ensuring everything was standardized. The same templates were used, the same labelling and naming schemes, the same headers etc. While this doesn’t seem like a big deal, it had some great benefits. Team members always knew what to expect when they opened specific types of pages, and the consistent labelling and naming drastically improved search.

Something as simple as using the same templates for similar information had a huge impact. Not only did it speed up creation (as editors didn’t have to fight with formatting/etc) it made it easier for agents looking up information as they know what to look for when they opened a page. Templates were also setup with standard labels, making it effortless to include them appropriately in search (and tie in with other macros like content-by-label).

Jira Integration

Much of a support team's work will be in Jira managing tickets. Fortunately, Jira and Confluence are highly integrated, and can serve up articles to customers (helping deflect tickets) but also directly to agents as they work on them. This helps speed up their ability to resolve tickets by serving up information directly to them. Having a well-maintained setup amplifies this as labelling and search will be cleaner, ensuring the appropriate information is given to them.

The Jira integration also makes it easy to link tickets to specific pages. This can support post-mortem and retrospectives as related documentation is attached directly to the ticket. This removed a lot of time spent searching for a particular ticket or specific page, making retrospectives much more streamlined. It also helped inform future documentation creation, as those creators could easily see what tickets were tied to a specific page, or which pages were referenced to solve specific tickets.

Wrap

I’ve found Confluence to be a great tool to support Support teams. It provides a centralized place for teams to look up, and add to, information, and offers a lot of integrations with Jira. Like any system, however, it does require maintenance, so be sure to think through how you’ll keep everything fresh and updated!

Maintaining a Confluence Space

A lot of work goes into deploying a successful Confluence space. This can take the form of extensive planning, stakeholder/customer identification and needs mapping, feature assessment and training. Groups that successfully navigate this challenge are rewarded with a useful Confluence space, one where users can quickly find relevant content and get on with their daily work.

Unfortunately many groups never get this far and instead they quickly deploy Confluence without appropriate planning or support. Even groups that do get this far, however, can quickly run into trouble if they don’t keep improving their space. All of the front-end planning and preparation goes out the window as everything falls apart.

I frequently use a library as an analogy for Confluence - without proper maintenance and updates it books would quickly be lost and users would become frustrated. Fortunately, maintaining a Confluence space isn’t too hard, and doesn’t have to require a lot of time or effort.

Schedule it out

The first step in maintaining Confluence is to make time to maintain it. This begins with simply scheduling time to sit down and assess everything. Personally I like to have a recurring calendar event every 3 months for this. I find 3 months is long enough for things to need updating, but not so quickly that I get burned out. That said, if you have large spaces, or particularly sensitive/important spaces, you may want to perform targeted reviews more regularly.

Scheduling it in advance also helps ensure it fits in with other priorities. Frequently groups realize they need to make adjustments, but already have a full calendar of other projects or things that need to get done. This makes it much more challenging as other priorities frequently win out over maintenance. It is, however, incredibly tempting to cancel or “move” your scheduled review. Resist that urge! Building the habit of regular reviews is important.

Get a team

It can be tempting to try and maintain Confluence all by yourself, or with a small group. While this can be possible with very small instances or installations, I find that getting more people involved both helps lighten the load but also improve the process. Getting more people involved gives you more perspectives on how things can be improved, and what can be added. 

Ideally you’ll have worked with a group in the past to improve or maintain your Confluence, however, you should always ask yourself if others should join in. You might be surprised at how many people want to help improve things! Including others in your group also exposes more people to Confluence, which can help build a group of super users you can leverage in other ways.

Get Feedback

Just like you shouldn’t jump into deploying a system without understanding its needs, you also shouldn’t just start changing things without feedback. You’ll likely have a good idea of what should be improved - after all you’re likely working in Confluence pretty regularly. Just like having a team gives you a better perspective on everything, gathering feedback on what should be improved is incredibly helpful.

This could be as simple as posting an instant message asking folks what they think would be beneficial, or more complex like a survey or short meetings to gather information. Regardless of how you gather this information, taking time to listen to the people using Confluence will give you some great ideas on what needs to be improved.

Adjust

After every maintenance cycle take some time to ask yourself what you can be doing better on an ongoing basis to keep things running smoothly. This could be as simple as keeping notes on what you did this round, or standing up a more complex process to update content regularly. Regardless, make sure you’re critically reviewing what you can be doing better so help keep things improving.

This is also a good habit to get into in general - consistently ask yourself how you can do better and soon you’ll find yourself improving

Conclusion

Keeping a Confluence space updated is simple - but not easy. Ensuring you have time is the biggest hurdle to overcome, but don’t forget to invite others along for the ride!

Planning for success

If groups are really lucky they may perform some planning when they first implement Confluence. This might take the form of engaging with a consultant, or using in-house workers to help plan things out. Many times, however, they just jump in and start using it. They might do this for a number of reasons, ranging from lack of talent, to perceived lack of time, to perceived lack of need. Regardless, this sets them up for failure.

On the plus side Confluence is fairly intuitive in many places, so groups are able to see some success even without proper planning. Where they run into issues, however, is when things begin to get more complex or as time goes on. I frequently see this expressed as individual groups or teams having a well-managed space or set of pages, but across the organization things are hard to find and manage. Frequently I hear that “Confluence is broken” - indicating individuals can’t find what they need.

The good news is that Confluence isn’t broken, it just isn’t being used properly. Systems are just toolkits, and if you use a tool the wrong way it’s not really the tools fault. Keeping this in mind helps me find a solution - just figure out how to use the tool, and an important part of that is planning.

What’s it take?

Planning involves a number of things, including figuring out who will be using your instance, what they need, what features you'll use and who will maintain everything.

Determine your audience

Determining your audience is the first step in planning, after all if you don’t know who is going to use Confluence you can’t meet their needs. Typically I start this by brainstorming by myself or with others to identify possible user groups. I try to keep these groups broad - “Engineers”, “Contractors”, “Customers” etc. 

Consider their needs

Once you’ve got a good idea of your audience you’ll need to think through their needs. What do Engineers need access to? When someone joins your organization what information is critical to a successful start? I begin this by brainstorming, but then I go to those groups and ask for their input. Frequently this helps me identify needs I couldn’t have figured out on my own. By the end of this step I’ll have a list of topics or other information to include for those groups.

Determine features

Only after I’ve figured out the audience and what they need do I dig into features. (Doing this backwards is a very common mistake… the needs should drive features, not the other way around!). This lets me make informed decisions about what specific features should be turned on. In the case of Confluence this means enabling specific types of content, looking into addons and figuring out access. Regardless of which specific features I use, I always keep the audience, and their needs, in mind when selecting them.

Maintenance

Determining who will maintain things, and how, is another important aspect of planning. I’ve seen many groups setup a brilliant Confluence instance, only to let it fall apart. Keeping things running smoothly involves identifying specific page owners to manage specific content, as well as a regular schedule of reviewing how things are going. I aim to review everything at least twice a year, this helps me stay on top of evolving needs of my customers and ensure Confluence is setup to support them.

Wrap Up

The good new is that planning doesn’t have to be a heavy lift. If you only have an hour or two that can still have a huge impact on making Confluence usable and setting yourself up for success.

Want to learn more about how to setup Confluence (and other knowledge bases?) - check out my Knowledge Base Fundamentals course to get a much deeper look.

Confluence Labels

Pages in confluence can be a range of great information. Tables, policies, attachments and more are all hosted information that helps teams thrive. Of course, that information is only useful if people can find it when they need it… and not being able to find what you need is one of the biggest challenges faced when using Confluence.

Fortunately there's a few ways to help improve findability. Things like grouping information under related parents, using keywords in titles, and setting up home pages are just a few. One of the most underutilized, however, is using labels.  Just like you might put a label called “Kitchen” on a box of moving supplies to know where it should go, you can put labels on content in Confluence to help others (including the system) know what to do with it.

What do they do

Labels also serve as keywords on a page, helping pages they’re attached to show up higher in search results. This is the first, and most obvious, way labels help. Of course, this only works if the labels relate to the keywords that are being search for, meaning taking time to plan out labels is even more important.

Labels also help search by allowing users to limit results to just selected labels. This can quickly narrow down a long list of search results making it much faster to find things. It also makes it very easy for someone looking for a specific type of content to locate it. It is especially useful for finding content across spaces if labels are consistently used.

The second way is through macros. Many macros allow you to filter for content which includes a specific label.  For example you can pull in a list of pages with only certain labels, or you can pull in page properties for just one label. This gives you a lot of flexibility - as long as your labels are good! Using labels this way makes it incredibly easy to create lists of related content, for example pulling every “how to” guide onto one page.

How are they created

As long as you can edit the page labels can be added to a page while editing (More Actions -> Add Labels) or when viewing a page by hitting the “L” shortcut. Labels are all lowercase (thankfully! Having them be case sensitive would make things a lot harder to manage), and cannot accept spaces. Confluence will, however, convert any spaces you have into a hyphen. This makes it easy for multi-word labels (“new-hire-onboarding”).

The labels on a page can be modified at any time, so it’s not uncommon for teams to regularly review and adjust their labels. Since anyone with edit access can modify labels, it’s also not uncommon for teams to make adjustments on the fly as they realize something needs to be changed.

Labels are unique to your Confluence instance. This means a label created anywhere will be available everywhere. This can be a bit annoying at times as different teams may use different variations of labels, but having the ability to search across all of Confluence for a specific label is a great benefit.

Labels best practices

Labels, like any tool, can be very useful if used properly, but it can be hard to figure out how to best manage there. There are some best practices I frequently use to help keep them being useful:

1. Plan your labels - Take time to sit down and think about why types of labels your space will use. Personally I find it useful to have a Confluence page where I track my labels. Typically this looks like a table with each label (or group of labels) listed out and a brief description of what they’re for. Examples include labels by team (“HR”, “Engineering”, etc)

2. Share your plan - Make sure the main groups of people creating content know what labels you plan to use and when to use them. This helps ensure creators know what to do.

3. Monitor labels - The “Labels list” macro shows a list of labels in a particular space. This helps you keep tabs on what labels are in use, and quickly find pages that use them.

4. Add them to templates - Templates can come pre-loaded with labels. This makes it very easy to set your team up for success by including specific labels on specific templates.

Too many labels

Labels can be created by anyone with edit access to that page. This is both good and bad. It’s good because it means anyone who can edit pages can add or modify labels. This empowers your team and lets them help keep things maintained overtime. It’s bad because it means anyone can remove necessary labels, or create new labels. It’s not uncommon to have several versions of a label (“eng”, “engineering”, “engggineering” etc) that have been created by different people over time.

This particular challenge can be overcome a few ways:

1. Monitoring - Regularly review the labels in use in your space and remove un-needed ones.

2. Consolidate - Combine similar labels where you can. For example you likely don’t need both “engineering” and “eng”.

Hard to find

Labels are also not immediately visible when viewing a page, which results in many folks simply not knowing they exist. This can make it challenging for teams to keep them up to date as team members might not know about them. This can be addressed by including information about labels in training when someone joins, and by actively monitoring pages. Taking even a few minutes every month to check what labels are in use can help catch challenges.

Space Homepages

When someone opens a space in confluence they'll be sent directly to its home page. This page is created when the space is created and serves as a landing page for the space. Every home page will come pre-built via a template that Atlassian has provided, which gives teams a great starting point for building a useful and compelling home page.

While it is created automatically and with a special template, a home page is basically the same as any other page in the space, however, there are a few specifics you should know about. These include a mix of technical features, like where the home page lives, and some best practices, like updating the homepage to make it useful.

Its at the top of the spaces hierarchy 

The home page is accessed by clicking on the name of the space, either in the Spaces menu, or in the top left of the navigation bar. The page itself lives at the top of the space hierarchy, which mainly means it won't appear in the content tree. This can make it a bit confusing for people who are new to confluence, but you can always get back to it by clicking on the spaces name in the top left, or via the spaces menu.

Having the home page be the top of the page hierarchy can, however, cause issues if the home page is changed (See the next section for how to do this), or if other pages are added to the top level of the space.  When this happens, those pages will essentially become invisible in the hierarchy. You can still search for them or link to them, but they'll be impossible to browse. This can easily cause frustration and friction as pages seem to disappear.

Changing the home page

By default the home page is the top of spaces hierarchy and is set when the space is created, however, you can change which page is the home page. This is done by a space admin and going to space details, and changing the space’s home page. This can be done at any time, so it’s easy to change back if you realize you made a mistake.

You can also see where the home page is in relation to other pages by opening the Reorder menu as a space admin. This will visually show you the home page with an orange icon, and every other piece of content under, or around it. This is the best place to find content that falls outside the home page (typically not something you want to do as that content won’t be visible in the space hierarchy).

The biggest issue groups run into when they change their home page is any piece of content not under the home page will seem to vanish from the space hierarchy. This can easily frustrate users as content will disappear (although it can still be searched for and linked to). Fortunately this is easily fixable by just moving that content somewhere under the new homepage.

Make it useful

The default template for a home page is a useful guide to help teams add useful information. Unfortunately one of the biggest mistakes I see is a team not curating their spaces home page. This is important as it's the landing page for the space, and should serve as guidance for visitors on where to go or what to look for in it.

Editing the home page is easy - just click the edit pencil (like any other page) and get started.  I think of the home page as a way to show people what's in the space, so typically I fill it up with links, references or general information. It can be helpful to ask someone who’s new to your team to take a look and let you know if they find it useful as their perspective can help you find blind spots in what you’ve added.

What you put on the home page will depend on what your space is for. A space for a team (Engineering, Human Resources, etc) might include information about who’s on the team, what they do or how to contact them. A space for a project might include high-level information like its scope, timeline or other information.

Confluence Whiteboards

Years ago I learned the “claw” technique for holding dry-erase markers. You take three markers of different colors and hold them between your fingers when you’re presenting. This makes it easy for you to switch colors to draw attention to something or make it stand out. Over the years I added holding an eraser in my palm to make it easier to remove things from my drawings. I really like this technique since it means I don’t have to keep walking back to a table to get a different color.

Much of my job now, however, involves working with virtual teams, and unfortunately sharing a whiteboard on a conference call is iffy at best. This means that the claw technique isn’t really helpful when most of my team is virtual. Over time this forced me to look into other tools, like draw.io or Lucidchart to satisfy my whiteboard needs. At the same time I primarily have used Confluence as my knowledge base / collaboration platform. This means I am constantly opening multiple applications to document a process, brainstorm and record information.

This certainly isn’t the worst thing in the world - however - it does mean I have to maintain (and pay for) multiple systems. This is where Confluence whiteboards come in. This is a (relatively) new content type that natively hosts a whiteboard within your Confluence instance… which has several benefits.

Context

Having the whiteboard appear in Confluence directly next to, under or above, related information is incredibly powerful. This means new hires can easily find related information, engineers don’t have to go far for API documentation and project managers have their planning diagrams in a single spot. Until I began using Confluence whiteboards I didn’t realize how important this was, but now that I have it I can’t easily see myself changing.

Whiteboards can be placed anywhere in the hierarchy you need. Typically I place them under a related page - for example system diagrams go under the page for that system. Whiteboards, however, can also be parents to other content. This makes it easy to include relevant information to support the whiteboard in a spot that’s incredibly easy to find.

Integrations

Like any other part of Confluence, whiteboards are natively integrated with other Atlassian products, mainly Jira and Confluence. This means that with a few clicks you can pull in any number of Jira tickets or Confluence pages. This has make it much easier for me to plan out things like sprints (by visually showing tickets on a whiteboard) Confluence redesigns (by visually moving things around).

Some upcoming features will also allow us to create Confluence pages based on whiteboard summaries - further improving our ability to quickly share information. This particular feature also helps teams better utilize whiteboards as many times I find they get incredibly broad. The summary page helps teams understand what the whiteboard is about.

Another feature will allow you to change fields on the ticket (such as assignee or priority) just by dropping it onto a section. This can help teams better manage their tickets by giving them a visual, hands-on, way to quickly edit multiple tickets.

Single tool

Many organizations these days have 100’s of different tools they manage and maintain, so (almost) anything you can do to reduce that number is a win. Not only is it a cost savings, it reduces administrative overhead, as well as frustration. The first is important as your information technology teams are likely already stretched thin, so having one less thing on their plate is important. The second is important as your workers won’t have to struggle to remember which system is for what. Instead they just open up Confluence and everything they need is in there.

Whiteboards are still a relatively new feature, however, I’ve found a lot of use - and removed my reliance on other tools. They’re available in all versions of Confluence Cloud (but limited in Free/Standard to 3 per person). Definitely worth a look!

Keep up with Confluence Comments

Confluence is intended as a collaboration platform, and one way it enables this is via comments. People can go onto a page, and leave questions, ideas or corrections at any time. This is a great feature since it allows anyone (or at least anyone with appropriate permissions) the ability to pitch in. (personally I do this a lot when I notice something seems to be out of date, misspelled or otherwise needing help).

Unfortunately I notice that many groups don’t follow up on comments - their pages end up riddled with yellow highlighting (indicating there’s a comment) that just sit there. At best this will result in a minor error (like spelling) not being corrected - at worst it can result in frustration and damage relationships. Fortunately, there are a few ways to keep track of comments.

Turn on (and monitor) notifications

If you’re @ mentioned in a comment, Confluence will helpfully send a notification to your email. This is the default behavior, but can easily get lost or ignored. I always recommend that groups keep their notifications on, and don’t filter them out of email, just to ensure they see them. I’ve also rarely run into someone who gets too many comment notifications, so realistically keeping them on won’t drown you in emails.

Generally I don’t find I get too many notifications (likely because many people aren’t commenting!), so when I do get one or two I take it as a good sign as people are actually engaging with my content.

You can control your notifications by clicking on your account name (in the top right, then on “Personal settings”.

Next click on “Email”, then review the options on the right.

Actively monitor your pages

If you’re a page owner you should also be actively reviewing your pages for comments (and other things like updates). Depending on the page you may do this more or less frequently, but making time to review the pages you own (and are ideally updating regularly) will help catch new comments.

Fortunately Confluence makes it easy to see those comments - just click on the comment icon at the top - and you’ll see them all pop out on the page. Personally I find myself reviewing my most popular / visible pages regularly to ensure I catch any comments, while less-used pages I check less frequently.

Search

You can search for comments in Confluence - however, without add-ons this can be a bit clunky as you’ll have to search for keywords in the comments to find them. Search also doesn’t currently support the ability to find unresolved comments, so you should rely on the top two methods to really catch them all.

Confluence for Project Managers

Confluence is a widely available tool that offers a lot of functions that support project managers. Unfortunately much of the time project managers are unaware of the various features available in Confluence that will help them better run their projects. These features include things like using templates to easily spin up content, databases to track tasks and whiteboards for planning.

Templates

Templates are pre build pages you can use to guide content creation. Confluence comes preloaded with over 100 of these, and you can even build your own (or modify existing ones) to better fit your needs. I find they serve two main purposes - making it easier to create content, and setting expectations for folks using that content.

One of my favorites is the meeting notes template, which I use for almost every meeting I'm in. If I have time I'll create it in advance so I don't have to enter attendees or other background info. This makes it much easier to write down real time notes on how things are going. The template comes with an area for attendees, an agenda, meeting notes, follow up tasks and decisions. Those last two use Confluence Macros to easily share information between pages, making it easy to pull in a list of every task or decision on a specific project.

Databases

Databases are what tables want to be when they grow up. They take the visual organization of a table, and expand on it. This allows you to more easily structure data, including adding multiple columns of information, linking in Jira tickets or Confluence pages, tagging individuals and more. I frequently find myself using them for project planning as they have a lot more horsepower than a spreadsheet, but aren’t as complex as a series of jira tickets.

Databases also allow you save views - for example a list of just items that are blocked, or assigned to a specific person. This makes it easy to share a link and empower stakeholders to get specific information at their fingertips - further removing roadblocks to important information.

Whiteboards

I used to spend a lot of planning using a physical whiteboard to draw out process flows, list ideas and more. While it's not quite the same experience, confluence whiteboards offer a great digital alternative to this. They are essentially an endless digital space where you can add shapes, lines and text to map out ideas, share brainstorming and more. They also allow you to pull in Confluence pages or Jira tickets, making it easy to represent existing work or knowledge in your diagrams.

They allow for easy collaboration across locations, with multiple team members being able to easily contribute or follow along. A recent addition also added the ability for folks to vote on items. This gives your team an easy way to indicate which things they think are most important, allowing you to focus on the biggest impact items.

Organization

A big challenge I run into on a project is organizing data. Confluence offers a number of different options to help with this, including things like labels, a nested content tree and folders.

Labels serve as meta data - information about content - that enable a number of features. Most apparently is improving search. Not only do labels impact search results, they can also be used to filter content. Additionally they tie into a number of marcos/page elements to automate things (such as gathering a list of content containing specific labels).

The content tree helps you visually organize information. For example anything related to your kickoff call could be put under the 'kickoff call' page. This makes it very easy for your team to find specific pieces of information quickly. These structures can be easily edited to via drag and drop, or even moved between spaces with a few clicks. 

Folders are a recent addition that serve as a way to group information without being information themselves. This lets you easily group information without cluttering up your documentation. For example, before folders were available I would frequently have a blank page in my content tree whose only purpose was to house other pages. It helped me organize content, but it didn’t do anything else. This cluttered up space and confused folks who ended up clicking on it.

These are just some of the Confluence features I’ve found helpful as a project manager. If you’ve got access to the tool I’d highly recommend checking them out and seeing what they can help you do!

Global Page Templates

Every space in Confluence can contain any number of templates. These allow editors to quickly format pages to speed up content creation and also set expectations of people reading pages about what to expect. Confluence even comes preloaded with 100+ “blueprints”, ensuring you start off with some great options.

When non-admins create a template it’s only usable in the space it’s created. For example if I make a new template (or edit one) in the “Rob” space, that template is only usable in the Rob space. There is a way around this when creating a page, however, most folks are unaware of the dropdown to pick different spaces and it adds extra steps.

This limitation, whoever, can be overcome with global templates. These can be created by Confluence admins (e.g. instance admins) and are available in every space in that instance. This allows your team to ensure everyone in your organization has access to the same set of templates.

Read on for more or check out this youtube video

Where do they live

Confluence admins can access global templates in a few places.

The first is by opening the Templates menu from any space’s space settings, then scroll all the way to the bottom. (It is under every blueprint, so I didn’t know it was there for quite a while).  Clicking on “Manage Global Templates” will bring you to the “Global templates and blueprints” admin panel, which is the second way to access them.

The Global templates and blueprints panel is accessible from the admin panel and is where global templates live. It looks and feels almost exactly like the templates panel from a space. The only difference is templates created or edited here will be available in every space.

Why is this useful?

Global templates are useful for a few reasons:

1. They ensure templates are available everywhere. This doesn’t seem like much, but it can be frustrating when you can’t find the template you want. Creating it as a global template ensures it’s available to everyone, making uniform content significantly easier.

2. They centralize administration. Without global templates may groups will make multiple copies of the same template in different spaces. This makes it incredibly hard to keep them all updated as each one is a separate template. Global templates remove this pain as updating it once updates it everywhere.
   
   
   

What else can you do on the global templates and blueprints page?

There’s a few other nifty things you can do from the global templates and blueprint page.

Manage blueprints - Blueprints are provided by Atlassian (or third parties) and are by default turned on and available in Confluence. These can be a great resource for folks looking for a template… however, they also clutter up the templates list, and in most cases they aren’t used. The global panel allows admins to disable them across the instance, freeing up visual space and reducing confusion.

Editing default pages - Admins can also change the default pages assigned to new spaces (including personal spaces). Doing this is helpful as it makes the beginning experience in a space more uniform or useful to the team.

New Confluence Feature - Folders

Up until recently the only way to organize content in Confluence was to put it under other content. For example if I wanted to organize all of my meeting notes in the same spot I would have to create a page called “Meeting notes” to be the parent for all the other pages.

This is a bit silly, as that “meeting notes” page’s only purpose is to serve as a place to put other content. It doesn’t offer anything new to folks, no new information, nothing.  Essentially it’s a placeholder that people can get confused by, or, at best, just another thing to click on on their way to somewhere else.

That, however, is all changing now that Folders are being released. The rollout began in mid September and will gradually expand to include everyone.

Keep reading for more and check out this video for a walkthrough

Embed Block

Add an embed URL or code. Learn more

What are folders?

Folders don’t contain any content themselves, instead, they allow you to organize content in your content tree. Other than not having any of their own content, they behave very similarly to other things in Confluence - you can rename them, star them, restrict them and more.

They allow you to more easily manage and organize your content by providing a way to contain information without requiring a page.

Why are they useful?

Folders are useful because they allow you to better organize content in a way that makes sense to your needs. Prior to this, the only way to do this was to create a page that didn’t have anything on it (or had very minimal information like the “child pages” macro). This served a similar function, however, resulted in non-useful content being added to your space.

What are some use cases?

Personally I take a lot of meeting notes in Confluence and I frequently end up with a string of pages just called “Meeting Notes” or “Meeting notes from Q1”. The only thing those pages do is serve to organize underlying meeting notes, so folders will easily replace those.

Other use cases I can easily see being useful include:

1. Support materials - Have a folder called “Get Support Here” (or something similar) and put any content related to support under it

2. How to - Another thing I commonly do is built out how-to articles. Now I can group them all under a single folder (or series of folders) to help my team more easily find content.

Can I turn folders off?

Yes, space admins can disable folders on a space-by-space basis. I cannot think of a specific reason to do this, however, if a group doesn’t think they’re needed they can be disabled.

Can I turn existing pages into folders?

Yes - any existing page can be converted into a folder. This will make it much easier to convert those placeholder pages. Even better, Confluence will save an archived copy of the original page in case you need it later. Just go to More Actions -> Convert page to folder.

What else should I know?

If you happen to have pages that are either blank or only have the “child pages” macro, Confluence will let you know you can convert them to a folder via a banner at the top of the page when you edit it. Personally I appreciate this call out, as it can be very easy to be complacent and leave those placeholder pages.

Types of content in Confluence

Confluence is a great tool for hosting content and storing information. Not all content, however, is the same. So, let’s take a look at the basic types of content that you can add to Confluence (at least as of the time of writing! Atlassian is constantly expanding and exploring new things to do with this tool, so I wouldn’t be surprised if this changed over time…).
Note all Blogs, Databases and Whiteboards can be disabled by a Space admin, so if you don’t see them check with your IT department or Space admin for help.

Keep reading for more, or check out this video walking you through them all

Pages

Pages are what most people think of when they think of content in Confluence. They’re a blank document that can contain any combination of text, images, attachments, macros and more. They’re also an easy entry as many people are already familiar with a document (Word, Google, Lotus, etc.), and many of the concepts and ideas behind word processing apply to pages.

Pages are also the only content type that cannot be disabled - meaning every space will always have this content type available for use.

What are pages for?

Here a page is used to detail a how-to guide

I find pages to be particularly useful for content that is perennial - that is it’s always useful or needed. Things like policies, team playbooks, how-to articles and the like are things that someone can always pull off the shelf and use. This is in contrast to “point-in-time” information, which we’ll explore down in blogs.

Pages also exist in the space hierarchy, meaning you can nest them under, or use them to use, other pieces of content. This allows you to build out a visual representation of information. For example a “policies” page could house every policy, or a page about a system could have everything related to that system under it.

What are pages not good for?

While pages are versatile they aren’t always the best at conveying visual information (check out whiteboards for that), and while they can house a table, they’re not the best at conveying structured data (check out databases instead). 

Blogs

Blogs look very similar to pages… they have the same editor, and they are (almost) visually indistinguishable from pages. That said, there’s a key difference - they don’t live in the page hierarchy. Instead, they live under the “blogs” link, and, unlike pages, they can be disabled on a space-by-space basis (so if you don’t see the menu, check with your space admin for help).

What are they good for?

Here a blog is used to share a project update

While blogs don’t appear in the space hierarchy, they do sort themselves chronologically. This makes them a great candidate for point-in-time information. Common examples I’ve seen include:

1. Product updates

2. Weekly data drops

3. Personal performance information

4. Team announcements

Information of this type tends to be useful in the moment, but quickly becomes outdated as things change (e.g. there’s a new release). This doesn’t mean it isn’t useful, just that we need to put different things in as a blog.

What are they not good for?

Given that blogs aren’t part of the page hierarchy they’re not the best place to put information that needs a general structure. For example, I can’t nest a blog post under another page, so using it for a how to article wouldn’t make sense. This also means blogs should be (relatively) contained and not outside context to fully understand.

Whiteboards

Whiteboards are what they sound like - a digital space to map, diagram, draw and collaborate. They allow users to collectively work on diagrams, brainstorm and manipulate objects in real time. Personally I prefer a big physical whiteboard, but frequently my team isn’t in the same office, so this virtual version is a great replacement.

Like pages, whiteboards appear in the space hierarchy, which is a great feature. This allows you to nest them under related information - think putting a system diagram under the page that details that system, or the sprint planning whiteboard under the sprint’s main page. This makes it incredibly easy for teams to quickly find related information, and to gain important context, about what’s on that whiteboard.

What are they for?

Here a whiteboard is used to map HR systems

Whiteboards are great for conveying, and collaborating, on visual information. Need to diagram a system? What about brainstorm how to improve a process? Diagram that process? All of that can be done in a whiteboard, and saved directly into the page hierarchy near related information. I find them useful any time I need to draw out my thoughts, or walk someone through a process (both things that are hard/challenging in other types of content).

They do also integrate with Jira, allowing you to pull Jira tickets into the whiteboard as objects. You can also represent confluence pages as objects. This allows you to easily pull in related information, or build page hierarchies visually.

What are they not good at?

Whiteboards are not good for storing a lot of text, or managing written information. They also don’t contain macros, so there’s not as many clever things you can do within a whiteboard (pages are better at that).

Databases

Up until the release of Databases your only option to represent data in Confluence was to use a table. Tables are great, however, they have a lot of limitations that Databases don’t. This includes things like:

1. Add different information, like dropdowns, to cells

2. Back link entries in one database with another (e.g. having one database list customers, and another list all the contacts for them)

3. Pull in Jira or Confluence information automagically

4. And more

What are they for?

Here a database is used to track project status

I find that databases bridge the gap between a page and a Jira ticket. They offer a lot more options for storing and sharing information than a table, but aren’t as complex as a ticket. This makes them great at helping organize information - think things like project plans, a CRM or marketing plan. They also have some great features allowing you to save various views (for example showing all the unresolved items) and easily share them with stakeholders. This makes sharing all that structured information a lot easier.

You can also copy the structure of database into a new one, which makes using them for similar needs a breeze.

What are they not good at?

While Databases are a great middle ground, there are times when you need more than what they offer. If you have a need to move things through a workflow or share outside of Confluence you might need Jira instead. Similarly if you have a simple use case - just recording names or a list - you might opt to go with a page instead.

Confluence Blog Posts

Confluence comes with two basic resources, pages and blog… Pages always made sense to me - they’re the stuff I put into Confluence for other people to use (there’s a biiiiit more to them then that, but I’ll cover that later). Blogs, on the other hand, remained a mystery for a while.

Personally I’ve always thought of blogs as something an individual or company will post online to share their thoughts on something. On the individual level the phrase “check out my blog” can be a bit cringe-worthy… and on the company level they can be a bit bland. This understanding may have caused me to ignore the Confluence Blog for longer than necessary, but I eventually figured out that they both exist, and are useful.

Where they are

Blogs exist in spaces (much like pages), however, instead of appearing in the “Content” section, they appear in the Sidebar.

This makes the visually one of the first things people will see when they browse the page (and something I glossed over for years..). Note that your Space Admin can turn off blogs, so you may not even see this option! If it’s missing, contact your Space Admin to see if they’ll turn it back on.

How they’re similar to Pages

Pages and Blogs share a number of similarities:

1. They exist in a space - Pages and Blogs exist in one, and only one, Space. This means they are generally controlled by Space access, allowing admins the ability to easily limit visibility by not providing access to the space.

2. They can be Restricted - Both resources can be restricted on the individual level, allowing authors the ability to hide, or control editing, one their content.

3. Robust editing - Both resources share the same editing capabilities (Headers, formatting, sections, etc).

4. Macros - Both support Macros, allowing you to easily extend functionality and interact with other resources.

How they’re different from Pages

While they do share many similarities, there are some major differences between the two resources that are important to understand.

1. Templates - Blogs do not support templates. This means you’ll be starting from scratch every time. Personally I get around this by using a (very) simple format for my regular blog posts (sometimes I Just copy/paste older ones).

2. Hierarchy - Blogs do not show up in a hierarchy (e.g. a blog cannot have a parent or children). 

3. Visibility - Unlike pages, Blogs can be disabled in a particular space by a Space Admin. This lets admins clear up space in the sidebar if they’re not used, but can make it a bit frustrating if folks are looking for blogs, but can’t find them.

4. Display - Blogs are displayed chronologically, allowing folks to browse by year or month. This differs from Pages, which are displayed in their hierarchy.

What I use them for

I started using blogs to capture “point in time” updates or information and left things that update over time, or are frequently looked at, to pages (e.g. “meet the team”, policies, etc). Over time this has included things like:

1. Weekly Updates - Details of what a team has accomplished over a week are a great thing to put in a blog… after all, it’s not like that will change over time, and having them in the chronological format makes it easy to browse through and see changes.

2. Product Releases - Another item that is a great “snapshot” of what’s happened, and easy to display chronologically.

Their chronological listing can also make Blogs a great way to capture performance information, or your accomplishments over time. This makes it easy to search for them since you can filter your search just to Blogs and anything with “achievement” in the title or label.

Other thoughts

Like any tool it’s important to consider WHY you’re using it before you just jump in. Personally, I’ve found Blogs to be useful to help chronicle activities over time, but groups may find other uses for them. Some groups may also opt to hide them entirely, and just focus on pages. Neither approach is better than the other, but in some cases one may make more sense for your team.

Challenges faced when updating Confluence

Confluence is. a great tool, but, like anything, over time it will wear down. Pages will get stale, content won’t be updated, and some information that should be there is just missing. Ideally organizations counter this by performing regular reviews of important or high-priority information in Confluence every 6-12 months. This helps ensure the tool remains useful and doesn’t get too cluttered.

Much more commonly, however, groups neglect to update Confluence, resulting in spaces and pages that are less than useful. Eventually someone will decide they need to do something about it - and run into challenges and opposition.

Below are several challenges I’ve come across (but are by no means ALL the challenges out there!), as well as some ways to get around them.

Challenge #1 - What is Confluence?

Someone not knowing what Confluence is, or realizing they have access to it, is more common than you think. On the one hand this is a bit crazy since organizations pay good money to utilize it, but on the other hand it’s entirely understandable as many times knowledge management isn’t at the forefront of anyone’s mind.

Overcoming this challenge can be hard as you’re working with someone who has zero understanding of the usefulness of Confluence. Here, focus on some of the following to help overcome it:

1. Education - Start with the basics. What challenges can Confluence help your organization solve? How is it already being used? What efficiencies are gained from it?

2. Demonstrate - I find it handy to have a demonstration space setup in advance so I can walk them through what a good setup looks like. This lets them get hands on to see what it’s like.

Challenge #2 - Where to begin?

Many times I find it challenging to pick a single point to begin - after all there can be dozens or hundreds of spaces in an instance, so choosing one to start improving can be hard.Even within a space it can be challenging to pick a single area to improve.

Taking an educated guess is a great way to overcome this challenge. Ask yourself the following questions to help target an area to start with:

1. Are there specific areas where most workers are required to go or would find information? Something like a company hub / employee central that houses general information can be an easy target.

2. Are there any areas that have low traffic? Low-traffic areas can be a good target for improvement, but you’ll have to determine if they’re worth it.

3. Is anyone screaming about it? You may be getting complaints that XYZ area isn’t up to speed - this makes this step easy, just go there and look a round!

Challenge #3 - "We don't have the resources"

Organizations have a lot of priorities, and I’ve never met one that put improving Confluence up near that top… this makes this objection incredibly common when you’ve identified some work that could be done. Typically I’ve found that more budget isn’t needed, making this a matter of getting some person-hours to help out. Typically I can tackle it myself, but sometimes getting another expert in is needed. 

Here’s a few ways you can approach this one:

1. Determine the minimal amount of work needed - Take your plan and boil it down to just the necessary changes or updates. Challenge yourself to make Confluence more useful while minimizing your ask. This is a good exercise in general, but will help you focus on the important parts.

2. Realistically estimate the work - Take some time to understand exactly how much time or money it will take to do what you’re planning. This won’t necessarily overcome this objection, but it will demonstrate you’ve done your homework, and set you up for the next item. This will also help you figure out what other folks you need to help you, and how much of their time you need.

3. Can you do it on your own - Many times I’ve found the updates I see are things I can do in my “spare” time at work. Sure, it will take longer since it’s just me dedicating a few hours here and there, but by taking on the core load yourself, you help deflate this objection.

Challenge #4 - Not a priority / “This isn’t important”

Another very common objection is that it’s not a priority for your organization. I completely understand this, as there’s a lot going on… however, as you’re likely aware, having a Confluence space that isn’t organized is almost worse than not having one at all.

For me, this challenge is best overcome by using numbers and gathering feedback. These both give you things to point at when making your case, helping show that it should be a priority.

1. Metrics - Pull whatever numbers you can on how much Confluence is utilized. How many times are pages with critical information accessed? How frequently are they updated? Are they even being used at all?

2. Feedback - Solicit, compile and analyze feedback from other people in your org about Confluence. What frustrates them? How much time do they waste struggling to find information? 

Challenge #5 - "It’s always been this way / It's not broken"

Organizational inertia can be very hard to overcome… folks get used to things being a certain way and become incredibly resistant to changing anything about it. That, however, doesn’t mean that we can’t do better.  Fortunately the way to overcome this is the same as Challenge #4 - gather information about the pain that is currently being experienced and quantify it.

Challenge #6 - "XYZ software does that"

Organizations have many, many tools (one place I worked had over 200!). This makes it highly likely there is another, similar tool, that does (at least part of) what Confluence does. Unfortunately this will result in folks pointing to the other software and saying “we don’t need to improve Confluence”.

My approach with this objection is education. Take time to clearly lay out the intended use of Confluence as the source of truth for information (or at least an index pointing the way). Reinforce that while information doesn’t have to live in Confluence, people should be using it as a first point of contact while looking for information.

Gathering feedback is also a good approach - especially if people are confused about where to go to get information or which system to use.

Challenge #7 - Resistance to archiving/deleting / No alignment on how to manage old content

This one pops up once you get your project started and have identified content that has to be retired. Content that has outlived its usefulness should be either archived or deleted as it just clutters things up for everyone else.

This pushback could be the result of a few things, so your approach will differ:

1. If they’re unfamiliar with Confluence - They may just not know you can safely archive items and still find them. If this is the case, educate them on how the feature works. Give them a live demonstration of how easy it is to archive, view, and recover, that information to help them understand how easy it is.

2. They think it’s still useful - Sometimes they’ll think that the information is still needed. This is where your metrics and feedback come in handy. In many cases you can show them that it hasn’t been viewed or updated in a period of time, or that only a small number of people use it. Getting hard data - or anecdotal data - can help them see that the content should be retired.

Challenge #8 - Resistance to using the tool

This is a very common challenge with Confluence in general. Many times people don’t want to use it at all, or only in a limited way. Overcoming this can be particularly challenging, especially if they’ve already made up their mind about it

Depending on how severe, this can take time to overcome, and is mainly education-focused. Take time to understand why they don’t want to use the tool, then tailor your response accordingly.

Challenge #9 - Disagreement on design principles

For me this is a less-common objection, but one that still does come up. Sometimes a group will have a particular idea of how things should be set up or look, which can clash with another group’s ideas. Taking time to understand each group’s desire is important here, as you’ll want to b e sure you understand their disagreement. 

From there, you may need to educate them on what is possible (e.g. you may not be able to do XYZ idea given constraints), or mediate a compromise with another path.

Confluence Databases for Project Tracking

Keeping track of all the pieces of a project can be challenging. Fortunately, there are a ton of different tools out there to get the job done. Recently, however, I’ve been using Confluence Databases to see how this feature can help me track project work, and I’ve found it to be pretty good at handling small to mid sized projects.

What is it?

Confluence Databases sit somewhere between a table/spreadsheet and Jira. They live in the content tree of a Confluence space, and look similar to a table. That is where the similarity ends though, as they have a number of functions that are very useful in tracking project statuses. This includes things like tracking specific users, linking to Jira tickets or Confluence pages, and even linking to other tables.

Features that help project managers

There’s a few specific features that I’ve found make a database very useful to project managers.

Saving (and easily sharing) filter views is incredibly useful. This allows me to create a view once, then share it with specific groups. I could, for example, share a list of new tasks with analysts so they can build out specs, or a list of blocked items to bring up at the start of our calls. Since the filter is saved in the URL this is as easy as copying/pasting, and can be bookmarked.

The native integration with Jira is another great feature as it’s highly likely I’ll be using Jira if I’m in Confluence. Being able to link a line in my database with 1 (or more) Jira tickets lets me keep my developers in Jira while still giving me easy access to what’s going on in there. This allows me to easily give my stakeholders a view of the project that isn’t too “technical” while preserving direct links to more information in case they want it.

Finally, configurations can be copied into a new database. This lets me easily make a clean copy of the database for a new project and preserve all of the columns and other settings I have. This means that once I have a good structure in place I can make as many copies as I need to, slot them into the proper place of Confluence, and not have to worry about deleting anything.

Database Setup

I’ve been using Databases to track relatively simple projects, so I added in a number of basic fields:

1. Task Name - A text field containing the name of the task

2. Status - A Tag field indicating the status (To Do, Blocked, etc) of the task

3. Owner - A User field with the task owner

4. Due Date - A Date field with when the task is due

5. Jira Ticket - If the task has a jira ticket it’s linked here

6. Jira Ticket Details - The assignee of the linked Jira ticket

7. Documentation - A link to any Confluence pages with more information

Why not just use Jira ?

There is an interesting question of why wouldn’t I just have used Jira to track my project work. There’s a few reasons:

1. Trying something new - I find it’s really important to expose myself to new ideas, tools and methodologies. Not only will this give me more options for managing projects, but I might find something useful that can be applied elsewhere.

2. Light weight - Setting up a Jira project takes time and sometimes requires a Jira admin to help with setup and changes. Both of these things may be in short supply, so having an option that is more robust than a spreadsheet (which may be flexible, but lacking features), but less heavy than a full-on Jira project is very attractive.

3. Presentable - I’ve found that many stakeholders don’t like going into Jira to get information on how things are going. Having another option, like an easily-accessible page in Confluence, has been great as people actually use them.

4. Flexible - The ability to easily add new columns, save filter-views and share information quickly makes databases very attractive. It hardly takes any time to add or adjust data, making it easy for my team to keep things up to date.

5. Integrations - Being able to instantly connect Confluence pages and Jira tickets makes Database more data-rich. For example teams can easily see any related Jira tickets, and stakeholders can easily access documents from one spot.

Why not just use a spreadsheet?

Spreadsheets are a great tool for many things, and they’re incredibly flexible. This makes them the go-to for many project trackers, especially if they don’t need specific features or integrations. That said, use a Database has a number of advantages:

1. Everything in one spot - If you’re already using Confluence you’re likely storing other project documentation in there as well. Having a database to track your progress puts everything in one spot, in the same system. This reduces the administrative overhead needed to track, maintain and manage things, and also leads to

2. Integrations - Aside from the built-in integrations with Jira, having your plan in Confluence makes it a lot easier to reference on other pages, integrate with other information and make more easily available.

3. Presentable - Similar to #3 above, I’ve found a database is easier to share with others, and easier for them to interpret. While a spreadsheet may have all the info in there, it’s easy for someone to go to the wrong tab, workbook, etc. and get frustrated.

4. Re-use - The configuration of a database can be copied into a new database in a few clicks. This makes it incredibly easy to spin up new projects with the same setup as an old one. A spreadsheet would require copying, then deleting everything to start over.

Final Thoughts

Databases are a great mid-weight way to track projects. The biggest hurdle for me was just figuring out what fields to include and after that I found them easy to update and use. Will they entirely replace spreadsheets? No, however, they do give project managers another great option to keep things on track.

New Confluence Beta Feature - Company Hub

Company Hub

Company Hub is a new beta feature for Confluence Premium and Enterprise that I think many folks will find very interesting. Up until this feature released we were stuck making a “central space” and hoping folks could find it.. but now there’s a highly visible, accessible page everyone can see to help direct them to content - the Company Hub.

See it live here!

What is it?

The Company Hub attempts to answer the question “What is one place everyone knows to go to for information”. It does this by making itself available in the navigation bar of every page, meaning it’s always visible. Prior to this feature the best way to solve for this challenge was to build out a space and call it something like “Employee Home” - but then you end up with folks not knowing where to look for it, losing it in a list of spaces, etc.

Features

The first thing I noticed in the Hub was the inclusion of two new macros (also available in Beta for Premium/Enterprise groups outside of the hub). Both appear to be aimed at helping folks more easily display information in a more visually pleasing way. Prior to having these I’ve been forced to use add-ons like Aura to make things look better.

The new macros are:

Cards

The Cards macro allows you to organize and display information visually. Each card can include information like a name and a link making it easier for folks to find content. I can think of a lot of good uses for this, from directing people to interesting pages, to lining up a process by step, to guiding new hires around the company.

Setting up cards

Setting up cards is simple - just add the macro, then adjust the general settings (applied to all the cards in the macro).

If a card is linked, you can have it also show the last time the linked page was updated, and the image for it’s owner (helpful so folks know who to go to or to judge stale-ness)

Settings per card

Each individual card also has information associated with it, including a link to other information, description title, and - interestingly - an integration with Unsplash so you can find images to add.

Cards of different sizes

You can also arrange cards in smaller sizes or vertically for more display options

Carousels

Similar to cards, these display a rotating series of up to three items and help you showcase information. 

These support up to three cards that users can click on for more information, or to link out to other resources. Each one supports a link, title, description and the same Unsplash integration as the Cards macro.

I can think of a number of uses for Carousels, ranging from highlighting regular information, to calling out specific parts of a how-to or process, or just breaking up the page with something that looks prettier.

Other Hub Features

While the Carousel and Card macros can be used on any piece of content in Confluence, there are a few Hub-specific features.

Naming

The default name of the hub is “Company Hub”…. which is boring. So, you can also name the Hub anything you want. This name appears on the Hub itself, but also in the navigation bar. I can easily see groups choosing something like “Home Base”, “Click here for info” or basically anything else to attract attention.

Permissions
The Hub also has its own permissions. These function almost identically to space permissions so you’ll have plenty of flexibility in determining who can view and edit the page.

One thing to note is that permissions are found under the “more actions” menu. Personally I find this a bit annoying as they’re a bit hidden, but they do function similar to Space permissions so you get a lot of control over who can do what.

Use Cases

Given the universal visibility of the Hub link in the Nav bar the Hub is an excellent place to put company-wide resources. Personally I can easily see HR/People teams leverage this to build a clearing house of information for workers - not only including pointers to HR policies, benefits, etc. but also things like

1. Calling out new hires - Use a carousel or card to link out to new folks

2. Company marketing materials - Link to the company blog, or references for workers (templates, brand materials etc)

3. Index team spaces - Provide easy access to each team’s spaces in Confluence

4. Company events - Hype up upcoming company events or provide access to the company calendar

Basically any company-wide information should be posted or linked from here. I wouldn’t use the Hub itself to host a lot of information, but instead leverage it for pointing folks to the appropriate spots. I also don’t think the hub should be a very long page - people should be able to use it to quickly find what they need and get to it - not scroll endlessly.

Potential Challenges / Limitations

Maintenance

Ensuring the Hub is regularly updated and maintained is another easy challenge I see cropping up (this is by no means unique to the hub!). If workers are told it’s the clearing house for information and find it to be out of date, incorrect or missing things, they’ll stop using it. That type of trust is very hard to rebuild, so groups using this feature should ensure they have someone regularly maintaining it.

Visible to Free / Standard

Less of a challenge and more of an annoyance is that the Hub is visible even for Free and Standard subscriptions… despite being unable to use it! There’s no way for admins to turn the link off, so those groups are essentially left with a sales-banner staring at them all day. (I certainly understand the need to upsell/etc. But having a way to disable the link would be nice).

It’s Beta

The hub is currently a beta release, meaning it can (and will!) change rapidly.There’s also a (very small) chance Atlassian decides that the hub shouldn’t be launched, meaning it would disappear.

Final thoughts

Overall I”m excited to see how more groups leverage the Hub. I think it’s a great feature that can help shorten the distance folks have to travel to find useful information. Certainly something worth checking out if you’re on Premium or Enterprise!

Mission Control for Confluence Spaces

One of the things that makes missions to space so successful is mission control - a room full of really smart people who help the astronauts solve complex challenges in real-time. While Confluence isn’t as complex as sending people into space, it still has levels of complexity that require us to manage it (and sometimes get our own room of smart people to help solve challenges).

Recently Atlassian released a feature called Mission Control that helps do exactly that. It lives in space settings and is full of resources to help admins manage their space.

Read on to learn more - and check out this youtube video detailing the feature.

Start at the top

At the top you’re presented with three metrics - the total amount of content in the space, the number of content views, and the amount of content created, plus a change over the last week for all of those. I find these three numbers are useful to determine how well the space is being utilized. For example, if the amount of content in the space spikes, it suggests something is going on in the related area. If the number of views falls off a cliff, I would want to dig into what happened.

Access questions

Next we get a view of access to the space in the form of external access and admins. I really appreciate having external access immediately available as I am (more than) a bit paranoid about external access. Seeing who the space admins are is also useful in the event I need some backup, or need to audit.

Metrics, Metrics and more Metrics

While the top focuses on high-level information about the general setup of the space, the middle gets into the numbers. For me this section helps me identify how the space is doing, and helps highlight areas I should look into. All this information can be displayed daily/weekly/monthly over the last 7/30/60 days via a selection at the top.

Metrics include:

1. Content views - The total number of views in the time frame, split by content type (pages, blogs, whiteboards).

2. Move viewed pages - The top 3 pages by visits. This is a great way to find your most popular content. Also includes a link to view ALL you content by number of views.

3. Content created - The total number of content created in the time frame. I find this more useful in spaces where I’m not the sole creator, or spaces with a broad audience. I use it to gauge how interested folks are in contributing to the space. A spike could suggest a new initiative or project, and a dip could suggest a project is winding down.

4. Content updated - I really like this metric as it helps me figure out how “fresh” the space is. Over time we can expect some pages not to be updated, but if we see a constant amount of updates being made it suggests that the space is live and being actively used.

5. Total content - The total amount of content to the space by type. Useful for seeing how a page is growing, and what types of content your team uses.

Managing content

Below metrics we get two more valuable pieces of information. Prior to Mission Control this information was available, but could be hard to get to. Having it all in one spot makes it MUCH easier to dig into and manage.

1. Inactive pages - Any page that hasn’t been updated or visited in 6 or more months. This is an incredibly useful thing to track as you should be either updating or archiving that type of content (e.g. stuff that’s not being used). Getting a list that’s easily accessible makes this process a LOT easier..

2. Pages without active owners - As folks leave your organization (or lose Confluence access) any page they’re an owner on will no longer have an active owner. This is an issue as the owner is the point of contact for the page and should be actively maintaining it. Getting a list of pages with inactive owners makes it much easier to go find new ones and ensure your content is maintained.

Security

The final section of mission  control displays the total number of active public links, and the number of views those links are attracting. I find this to be very useful information - but only if you have public links turned on.Personally I’m a bit paranoid about publicly facing information, so having these metrics easily accessible helps put my mind a bit more at ease.

1. Active public links - The total number of active public links in the space (including a link to see them). Spikes in this metric could suggest someone is sharing information they shouldn’t, or that a new initiative is going live that requires public links. Either one should be investigated to valid it’s an appropriate use of the feature.

2. Public link views - The number of views made against public links. Similar to the active links, a spike could just mean something went live (e.g. a new feature or guide), or could suggest your links are being abused in some way. Definitely worth checking out if you see spikes in the metric.

Final thoughts

Mission control is a great step in the right direction for helping manage spaces, particularly ones that are accessed by larger groups (e.g. employee hubs) or are for sensitive things (e.g. special projects). Having access to all this information in one space is a very useful tool and one I hope to see more of in the future.