Project Type Showdown, Request Types and Queues : ACP-420 Study Session #3

ACP-420 session three is in the books (embedded at the bottom of this page too)! We picked up right where we left off with team vs company managed projects, and got through setting up queues (more specifics on those topics below).

Study Tip

If you're in my sessions have a Jira service management instance up and follow along live. This will let you see the concept, but also uncover questions you may have and ask them live.

Topics

• Team vs Company Managed Projects

  These two project types certainly bring up conversation!  While both offer the ability to collect and manage tickets , they differ quite a bit on the management side.

  Team managed projects let the project admin adjust almost everything. You can add request Types, change workflows, add fields and more. This gives smaller, less technical, teams a lot of flexibility.

  Company managed project, on the other hand, have a wider array of features, but limit what a project admin can do. You can still make request Types, but can't modify workflows, fields, screens, notifications or access. This is because company managed projects use schemas, or shared configurations.  Schemes let an orgnaization share configurations across projects, vastly simplifying administration.

  There is some debate about whether groups should ever use team managed projects (ill dig more into this in a future blog post), but for the ACP-420 we are expected to know the differences.

• Request Types

  Request Types are customer facing forms that let customers out in tickets. Project admins can set them up and modify them as needed, including things like hiding fields, grouping in the portal and having more customer friendly field names.

  • In a company managed project these are all tied to an issue type, which provides the workflow for the request type.

  • In a team managed project there is no issue type, so each request type has its own workflow, fields and more.

• Queues

  If request Types are how customers enter tickets, queues are (one of) the main ways agents interact with them. Queues are essentially saved searches that project admins manage to guide agents on which tickets should be solved.

  Agents can select queues to view, but only project admins can edit queues. This means that we, as admins, need to take time and effort to craft queues that best support our teams. Admins can do things like

  * Define the tickets in the queue - this is done via Jira search (basic or jql) and can be refined at any time

  * Define what columns are displayed and in what order - this allows admins to tailor what information is easily access access

  Queues can be grouped into 'priority queues', basically groupings project admins select. This helps further guide agents by helping them work in one spot and not having to jump around between parts of Jira.

Questions

1. Why would anyone use a Team Managed project?

   1. It gives teams more local control of their project and removes reliance on a Jira admin (something many company's don't have, or have in limited supply).

2. Why would someone NOT use a team-managed project?

   1. Eventually many teams outgrow a team-managed project or need more support so they need to be converted. This takes time and effort, which can be avoided if you just start in a Company-managed project.

3. What is a “Jira-ism”?

   1. Anything that makes you hang your head in disappointment over decisions Atlassian makes that common sense would tell you could have been implemented in a much better way

4. Where can I get a recording of the sessions?

   1. Here!

5. When I go into Project Settings why does “request type” not appear?

   1. Request types only exist in Service projects, so you’re likely in a Business or Software project if you don’t see Request tyeps

6. What is a PICNIC?

   1. Problem In Chair, Not In Computer

   2. (Note - this won’t be on the exam!)

7. Why would I hide a request type from the portal?

   1. I do this to let my agents enter specific types of tickets but not customers, for example “hardware request” could be something only agents can enter after they think new hardware is needed.

8. Why should I bother changing the request type icon?

   1. The icon helps differentiate request types and makes the customer experience a bit better

   2. It also makes it easier for agents and admins to differentiate tickets easily

ACP-420 Jira Service Projects Study Session #2 Notes

Big News

It looks like the ACP-420 certification is getting a makeover. This is good news, since it means the content will be fresh and relate to new features... but also has a few implications for us. The biggest one is we won't be able to sit the exam until after April 15th (meaning my goal of passing by April 1st isn't possible!). While this could be frustrating, it does give us more time to prepare - especially since new content will likely be included.

Topics Covered

We got through most of the topics I hoped to. Below is a synopsis of what we covered (all in my own words - definitely review the great free training in the University!).

Check out the full recording here

Core Features

1. Issue types have their own workflow, and can have many request types

2. Request types are customer-facing and are associated with one, and only one, issue type

3. Workflows are the series of stages an issue type has, including transitions between them

4. Queues are saved views of tickets that agents (people who work on tickets) use to keep track of what to work on next

5. SLA's (Service Level Agreements) are time limits on tickets. These help agents prioritize tickets based on how much time is left.

Incident vs Problem

This concept appeared a few times, and is an important concept to understand in general (they’re also something I get mixed up quite a bit!).

• Incident - something that happened. e.g. I see an error message, a website doesn’t work, etc. I also think of this as being the smoke a fire creates.

• Problem - the underlying thing that caused the incident(s). e.g. a server was unplugged, there’s a bug in the code, etc. If the incident is the smoke, this is the fire.

Understand the different is important as we handle them differently. Personally I tend to see incidents well before problems - after all there’s a lot of users out there, so they tend to notice things first (although this isn’t always true!).

Use Cases

There are a number of different use cases for Jira Service Management. Honestly I’m not sure these will take up a lot of space on the exam, but definitely good to keep in mind as I bet some (or all?) may show up in your career!

Here are the use cases listed in the training course:

• Incident management - Managing incidents

• Problem management - Uncovering and resolving problems

• Change management - Handling changes to systems or processes

• Knowledge management - Keeping track of updates to knowledge articles/resources

• Asset and configuration management - Assets are our computers/software, and configuration is how they’re setup

Best Practices

I appreciate these appearing so early in the course. Many times we get stuck on the mechanics of a system (how does an SLA work, how can I enter tickets) and forget all the things that happen around/before that part (planning, validating use cases, etc). The best practices provided by Atlassian relate to things like gathering requirements before you begin, keeping things simple (always a good idea!) and using naming conventions to make things easier to use.

Another best practice that really resonated with me was to test things before you deploy them. I’ve personally not done this (and suffered for it!) - so I highly encourage everyone to test everything before you deploy it.

The section finished up by reminding us to be Jira Champions - people who use Jira regularly and make it part of our regular practice and habit. This is easier said than done (and something I’m guilty of not doing all the time! :D). It is, however, a good reminder - even if we earn the ACP-420 certification it doesn’t mean much if we don’t apply what we learn and share it with others.

Overall I found that these best practices don’t only apply to Jira Service Management - they can be applied to any system or practice.

Map Business Requirements

One of the first projects I worked on spent months mapping business requirements. They had dozens of sessions to understand what the business needed, included subject matter experts from all over the business and had several people focused entirely on this step. It felt like overkill at the time, but once we got to deployment, things went really smoothly. This taught me the importance of understanding the business requirements, understanding what the system can do, and the importance of bridging the gap.

This section focused on exactly that - talk to your users, understand their needs, and then figure out what in Jira will help them do that. This can be easier said than done as there can be a lot of folks to talk to! Fortunately Atlassian has some basic questions to ask, and splits those questions up by group (individual contributor and managers). While this certainly sin’t everything you’d want to do or ask, it’s a great start in understanding what is needed.

There’s several important reminders in there as well - like not over-engineering, and making sure whatever you create actually meets their needs. (It can be very easy to forget deploying Jira is a partnership and not just us telling them what Jira will do for them!).

What we missed

I had hoped to talk about the differences between company and team-managed projects and just ran out of time! We spoke about them briefly, but we’ll pick up there next week.

What’s next?

Next week we’ll pick up right where we left off! I hope to get through the following topics - which should get us more hands-on!

• Company vs. Team managed projects

• Map business requirements to Jira configurations

• Compare company-managed projects and team-managed projects in Jira

• Choose a project template in Jira

• Set up requests and queues

• Set up your services in Jira Service Management

• Configure SLAs to manage service quality goals

What it means to be a system admin

I ran a live training recently about being a Confluence Space Admin. In the context of Confluence, a Space Admin has specific privileges to do things like control access to a space, modify features, etc. The session covered the technical aspects of what admins can do (e.g. features to help manage everything, access controls, etc) but also discussed a more important topic to me - the non-technical responsibilities of a system admin. 

Non-technical importance

Frequently I find that individuals forget about the non-technical side of being an admin… after all, it is very exciting to get admin access to something. It means you get something special, something extra, that most folks never get. It also, however, means you accept a large responsibility - ensuring your system runs effectively and supports its users.

Personally I’ve been caught up in the excitement of being given extra access. There’s new buttons to go push, new things to learn and a big sense of power. Depending on the system the amount of power can be on the smaller end (resetting passwords and the like) to extremely sensitive (access to home addresses or social insurance numbers). Being an admin means being trusted with that access - and by extension to power and responsibility that comes with it.

The best advice I was given about being an admin was in the context of managing a human resources system that had social security numbers (United States government ID numbers). The senior admin told me that “Our job is to make sure the numbers are correct, not to use the numbers”. This had a huge impact on me as it highlighted the importance of making sure the system was accurate, regardless of what the information was.

“Our job is to make sure the numbers are correct, not to use the numbers”

— Sr Database Admin

For me this is what is important about being an admin. You don't only need to consider what the system does (serve up info, support collaboration, etc) you need to understand why you need to do those things and keep an eye on everything around the system. This includes things like planning, maintenance and leadership. Typically one, or all, of these things is forgotten, resulting in systems that are 'broken' (if you ask their users).

What should admins spend their time on?

For me, admins should be spending most of their time planning out how their system can be successful. This doesn’t mean we ignore the tools or features we have, but it does mean we think about the best way to use those tools to help our team. It also means we have to understand what our team needs to do and why they need to do it. For Confluence this could be thinking through an optimal structure, or figuring out what content is missing and how to get it. That said, it also means understanding what our team is trying to accomplish. For example if they need to onboard new hires they’ll have different needs than if they need to support customers.

Maintenance is another area that admins need to be very active in. It's not glamorous, it won't win awards, but it will ensure your system supports the people using it and that it is relevant to them. Maintenance means regularly review how the system is used, digging through content to ensure it’s updated and similar activities. In my experience most of the complaints about Confluence not working related to stale or content that is hard to find - two things that fall squarely on admins to manage.

Active Admins

Being an admin isn't a passive job (although it's easy to fall into that mindset!). Instead admins need to be active and lead their team in how their system is used. In general this should take the form of getting training on the system, reading manuals and talking with your team. For Confluence this can take the form of training users in best practices, building onboarding documentation and showing folks how things can work.

There is a lot that goes into being an admin, and it's incredibly easy to think it's only about the technical side or things or the extra access. For me, however, being an admin is a privilege and a burden. Admins enable their teams. Admins keep things running. Admins allow others to excel.

ACP-420 Managing Jira Service Projects Certification

I’m hoping to earn the ACP-420 certification! Join me for free, live study sessions every Tuesday at 6 AM PST now until March 28th.

I’ve been using Jira Service Management for a while now, and, like many systems, I never had any official training on it. Instead, I learned how to use it by doing, asking questions, and tripping over mistakes. This approach isn’t a bad one as it helps cement in lessons and gave me a great deal of confidence in figuring things out on my own.

It does, however, have a weakness - there’s a lot of aspects of Jira Service Management that I never get exposed to, or I only learn partially. This might be because the group I work with doesn’t use specific features so I never get exposed, or it could be because I figure out a way to do something that doesn’t include aspects of Jira Service Management. Regardless, it has resulted in gaps in my knowledge of how this system works - and by extension my ability to support my team.

What is this certification for?

So, to help plug those holes I’ve decided to pursue the ACP-420 Managing Jira Service Projects certification that Atlassian offers. ACP-420 is concerned with ensuring folks know how to manage and configure Jira Service Management for Cloud (sorry Data Center folks!) and covers a wide range of topics, including:

1. Translating business requirements - Knowing what a business is trying to do is critical in provided proper support. This includes taking their needs and translating them into things Jira Service Management can do.

2. Setting up project features like request types and SLAs - Jira Service Management has a ton of features. Understanding what they all do, how they impact the team, and how to configure them is paramount.

3. Managing permissions and notifications - Two of the most frustrating areas of Jira Service Management are being able to access things, and getting notified properly. As admins we need to know all about these.

4. Setting up dashboards and reporting - Providing teams with insights on how to improve their process or identify bottlenecks is a big part of knowing the system.

5. Setting up the intake portal - Tickets have to get into Jira Service Management somehow! Knowing how the portal works, and how to configure it, is important.

6. And more!

Why should I get certified?

I find there’s a few reasons to get certified. First, it helps improve our knowledge. Second, it may be required for our jobs, and third it can open a door for us.

I find the first reason the most interesting as I’ll learn more about the topic. As I noted above I tend to learn by doing or by necessity which means I end up with gaps in my knowledge. Earning a certification forces me to learn things I may not have otherwise had exposure to, resulting in a wide range of knowledge

Depending on your job a certification may also be required. Not having a certification like ACP-420 can mean not being considered for possible roles, or not attaining a promotion at work. The effort put into earning the certification can be well worth it (and many company’s will even cover the cost of the exam!).

Holding a certification also signals to others that you know a bit about that topic. While having a certification doesn’t mean you know everything about a topic, it does signal you know a certain amount. Having a certification can then mean you’ll have more opportunities open to you as others will see it as proof of your skills. This can make it easier to get interviews - after which your experience takes over.

Join me to study for the ACP-420

The biggest challenge earning a certification for me isn’t usually the content - it’s making the time to actually study! Between work, family and other things it’s incredibly hard to find time to go through the training materials (all of which are provided free by Atlassian). So, to help me get this done I’m hosting free, live, study sessions every Tuesday morning at 6 AM PST.

These sessions will be a shared time for us all to prepare for the ACP-420. We’ll go through Atlassian’s training, as well as help answer each other’s questions. I’ll also be summing up my study notes and sharing them here for folks to use.

Additionally, I’ve got 3 free exam vouchers I’ll be giving away. If you win you’ll be able to take the ACP-420 for free (provided you take the exam by June 1st, 2025!).

Resources

1. Atlassians page on ACP-420

2. Free training for ACP-420 (What we’ll be using!)

3. Sign up for my study sessions (and other great live training)

Don’t worry, get HAPI

Quick note! This blog post is sponsored by ScriptRunner.

What is scripting

Check out my prior post for more information on what scripting is. In short, it’s a way to expand what a system is capable of, and to allow a system to meet a specific use case. It is a very powerful tool… however, it can also be a bit challenging (and intimidating!) to learn.

Unless you have a background in writing scripts, getting started can be incredibly confusing. Systems will use different types of scripting, meaning lessons you’ve learned in one system may not apply to another one. If you don’t have a background in scripting, even the basic concepts can be challenging to learn as they can be unlike anything else you’ve done in the past.

Many scripting languages are also incredibly complex, requiring you to understand a variety of topics, but also know a wide range of commands. While this complexity can be warranted to support various use cases, it makes it very hard to learn it.

Jira is Groovy (well, it uses Groovy)

A lot of scripting in Jira relies on Groovy - a scripting language that has a lot of power and makes it easier to use Jira’s APIs (Application Programmer Interfaces). That said, it also has a bit of a learning curve - even if you know another scripting language like Javascript. Unless you happen to have a deep set of technical skills or a background in scripting, you may find yourself quickly overwhelmed with its “easy to learn” setup.

Personally, I find this to be a shame, as almost every group can benefit from scripting. It allows admins to unlock a lot of potential, and to alleviate a lot of manual processes that teams go through. This is especially true for teams using Jira, as many times there are steps in their process that can, and should, be automated.

The high cost of entry for Groovy means that many admins simply won’t learn it. If they’re very lucky they’ll have another resource at their company (or a contractor) who can help script, but many times they simply won’t have access to this powerful tool. Even if an admin does know scripting, they may find themselves lacking the time necessary to write out useful scripts.

When an admin gets lucky and happens to inherit a good script or have someone else build it out, they may find themselves in trouble as they may not understand the code. This makes it hard to troubleshoot issues or bugs that may crop up, but this also makes it hard to modify the code if they want to. Adjusting existing code is a very common approach to improving things, but if it’s too confusing to figure out, admins will simply not get those benefits.

When admins are lucky enough to have existing code they might also find themselves lacking any documentation about what it does, or how to adjust it. Poorly documented code is nothing new, but it still represents a big challenge. This reliance on “tribal knowledge” can make it impossible for an admin to make progress, or even understand what a specific script does.

How ScriptRunner’s HAPI helps overcome those challenges

Despite all of these challenges, scripting is still an incredibly valuable tool for admins. Fortunately, there is help out there in the form of HAPI. HAPI provides a simplified structure for interacting with Jira Groovy scripts that is substantially more intuitive writing scripts in Groovy without HAPI.

For example, this bit of Groovy code

Can be rewritten in HAPI as 

Not only is the new code substantially shorter( 4 lines vs 30) it is vastly easier to read and understand. I bet after you read the HAPI code you could explain what it does to someone else… much easier than just the pure Groovy version above!

This readability is one of the biggest advantages HAPI provides - simply read it left to right like you would a sentence in English to know what it does. For example, the code above could be read as 

“Create an issue in the SSPA project with the Task type. Make the summary “I need to create a ticket” and the description “well, that was easy”. 

Imagine being a new admin and being able to decode your scripts this quickly (or make new ones…)!

Seamless integration

HAPI is an extension to ScriptRunner, which might make you wonder if they play nice together. The good news is they do! Scripts using HAPI can seamlessly integrate with existing ScriptRunner scripts. This means groups already using ScriptRunner can easily add new scripts utilizing HAPI, but also easily refactor existing scripts to be more easily readable. Even better, scripts you write can use both HAPI and more traditional Java API calls in the same script so you’re not forced to choose one or the other.

This backwards compatibility is a great feature and means that even if an admin doesn’t know Groovy (or doesn’t want to risk breaking existing scripts), they can easily add new HAPI scripts to their environment. 

Quality of Life (QoL)

If HAPI stopped there and only made scripts easier to read/interpret and was compatible with Groovy, it would be amazing. Fortunately the nice people at ScriptRunner have gone a few steps further to make HAPI even more useful for admins.

One way they’ve done this is by adding auto-complete for your custom values. This means that as you type in commands, HAPI will start showing possible valid entries based on what you typed. This drastically reduces the risk that you’ll mistype a command, or pick one that doesn’t exist. Personally, I find this incredibly useful, as I typically find myself opening up documentation to double-check what commands there are.

In the example below we can see HAPI serving up possible completions to “setD” - something that Groovy does on its own.

HAPI, however, takes this a step further by pulling in valid options for fields. For example, if you wanted to add an issue to a project, HAPI would display a list of valid project keys in the code. Without this feature, you’d either have to look up what you wanted, or memorize every project key (trust me, don’t try this one!). By displaying valid options for fields directly in the code HAPI saves admins a lot of time.

In this screenshot we can see HAPI suggesting possible valid values for “Assignee”:

HAPI also works with other ScriptRunner features. For example, it can be used to build out custom listeners (scripts that detect when a specific event occurs, for example an issue being created or a field changing a value). While this can be done in with Atlassian’s APIs, having all of the features mentioned above make it substantially easier. Similarly, you can use it to extend Jira’s standard UI - again leveraging all of the benefits of HAPI in an existing (very useful) feature.

Availability

HAPI was originally built out for Jira Data Center (DC)... but the great news is it it is now available on Jira Cloud!

Conclusion

HAPI is a big step forward in terms of scripting in Jira. Its backward compatibility with existing ScriptRunner scripts, and the wide range of QoL features make it a great choice for admins looking to automate things. These features also make it a lot more approachable to someone who is just beginning to learn Groovy as it has a much flatter learning curve. Even better, it helps eliminate a need for a deep understanding of Groovy or Jira API’s, making it much more approachable to basically everyone.

Curious to learn more? Check out more info here!

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.