📄 Advanced Editing | ACA-920 Confluence Essentials Session #3

Last week we covered the basics of editing - including things like making pages and how to use the editing functions… now it’s time to get a bit deeper into what options are available for us when we edit pages.

Atlassian Intelligence (AI)

AI is available in Cloud Premium and Enterprise and offers some interesting tools to help us edit our content. At its most basic AI can help us generate ideas or create things like outlines. Personally I find this useful for helping get past writer’s block as it can help redirect my thoughts or help me get over being stuck. AI can also change the tone of what we’ve written, which can be helpful if our audience changes (or if we can’t get the tone quite right).

There are, however, more interesting use cases for AI that I’ve found. One is its ability to summarize content. Instead of having to read an entire page, you can have the tool simply summarize it for you. This is great for longer pieces of content, or, more commonly, when I’ve found something right before a call and I don’t have time to read everything. Summarize also works on recent changes - something I find to be very useful. Some pages change very frequently, so having the tool just summarizes what’s new since I last viewed it helps me stay on track and understand what’s changes.

Another useful tool is the ability to define terms and acronyms. At first I didn’t think I would use this all that much, but I’ve found it to be one of the better features… especially if I’m new to a team or unfamiliar with how they operate. (New joiners also find this very useful!). It helps us understand what these terms mean, and also gives us context for why the tool thinks that is the definition in the form of links and references (to help rule out hallucinations.

Macros

Our next stop in the advanced editing section was on Macros. These are essentially small programs or extensions that give us more functionality in Confluence. This can be a basic thing, like adding a coloured panel to a page, or a more complex thing, like mirroring content across multiple spaces. Macros are available either from the “+” menu in the edit toolbar, or by typing in “/” when editing (my preferred method).

There are many, many, macros, so we didn’t talk about all of them, but there were some favorites:

1. Table of Contents - dynamically builds a linked table of contents based on headers. One that I use on almost every single page I build as it makes it much easier to find things.

2. Excerpt - defines an area of the page that can be pulled into other pages. Allows you to mirror content - something I use frequently for “background” information that can be pulled into an index.

3. Expand - Puts a collapsible section on the page that can show, or hide, information in it. Helpful for breaking up the page and managing what’s visible.

4. Panels - Adds a panel to the page that includes colours. Useful for visually calling attention to something (like a warning).

5. Labels list - Displays a list of all the labels in a specified space. Helpful for managing labels (particularly identifying near duplicates).

I am working on a series of youtube videos that break down the common macros - so stay tuned for something that is (hopefully!) fun!

Restrictions

We finished out our advanced session by talking about Restrictions. This is probably the most confusing part of Confluence for most folks, so taking time to understand them is important! The ability to add a restriction to a page is a Space-level permission. This means your space admin can allow, or prevent, you from adding them (so if you don’t see them, chat with a space admin!). 

There are three types of restrictions:

1. Everyone can view and edit - Anyone who has view access to the space can see this page, and anyone with edit access for pages can edit it. This is the default, and most permissive, permission.

2. Everyone can view, only some can edit - Anyone with view access to the space can view it, but only people specified in the restriction can edit the page. This is fairly common as sometimes only specific people (e.g. experts or certain folks) should be able to change things.

3. Only some can view or edit - The most restrictive. This hides the content from anyone who isn’t on the “view” list, and prevents editing unless you’re on the “edit list.

There are two considerations we have to keep in mind that commonly trip folks up (and given their importance are very likely going to show up on the exam if you take it!)

1. View permissions inherit down to children - This means if Page A has a child, and I restrict View access on Page A, it’s child will also be restricted.

2. Edit permissions do not inherit down to children - This means if I can edit Page A, it doesn’t necessarily mean I can edit it’s children.

Check out the recording below - and hope to see you in the next session!

🧵Atlassian Loom for Beginners

Despite chrome constantly crashing I had a great time showing folks that he basics of Loom. I find it a great tool for recording audio, video screen shares and screenshots, and even better it integrates natively with confluence and Jira - two tools I love in constantly.

The App(s)

Loom has two apps - a chrome extension and a desktop app (both downloadable here). My Loom journey began using the chrome extension, which is a great, lightweight way to record Looms (Looming?) and save them to your library (what Loom calls your storage). Of course this only works/makes sense if you happen to use Chrome, but if you do it’s a great way to quickly begin Looming (on second thought maybe I’ll call it weaving?). Clicking the Loom icon immediately opens up the recording panel where you can decide how you’d like to record. You can optionally include your screen, video and audio, letting you record the range from silent screen recordings to fully A/V walkthroughs of something.

Recently, however, I’ve started working with the desktop app, which is a bit beefier in terms of size, but offers more features(namely recording and screenshots via hotkeys, drawing on screen and capturing mouse clicks). The additional features have made it more attractive (especially the hotkeys and capturing mouse clicks) as they speed up by workflow and make it easier to clearly indicate what I intend to share.

Library

Once recorded Looms (what I'll call a screenshot or recording from. Loom) are stored in your Library. This is basically cloud storage that you can organize to easily keep track of Looks, but also let's to easily share and collaborate. Collaboration takes the form of comments, @ mentioning and shared-editing (more on editing below). Comments can be dropped on an overall Loom, or at specific timestamps (something I find really useful when I need to point out a specific question or clarification).

In addition to your Library you can also add Spaces to Loom. These function similarly to a Confluence space and let you organize content by whatever grouping you like (team, department, product, etc). Spaces can be public or “closed”. Everyone in your workspace can see all open spaces, but have to be invited in to see closed spaces. This lets teams keep sensitive information private, while being able to easily share with those who need it.

Editing

Once recorded Looms can also be edited in the cloud - either by you or shared editors - making it very easy to quickly create content. Other solutions I use will provide either recording or editing, so having both in one spot, and an easy to use interface, is a great win.

Editing can be as simple as cutting a few seconds of lead, or removing and replacing sections with other videos. You can also easily add shapes, texts and call outs to the video - as well as a button linked to a page or other content.  With the premium tiers you'll also have access to some AI tools to help remove pauses and/or filler words (although personally I haven't used these).

Integrations

Loom is made by Atlassian, the same company that is responsible for Jira and Confluence, and their main focus is on helping teams work better, together. This is expressed in Loom by having native integrations with Jira and Confluence, letting you instantly start recordings from Jira tickets or Confluence pages. I’ve found this to be a really useful (and time saving) feature as I can create recordings in the moment I’m thinking about them vs. having to wait and figure it out later.

Pricing

As of writing Loom has a free tier which allows you to have up to 50 people in the same workspace. They’re limited to 25 total videos, but it’s a great way for smaller teams to quickly share visual information. As you go up in tiers you get access to more storage, editing and AI tools. Personally I haven’t used the AI too much so I’m unsure if it’s worth the cost, however, the editing features do make the premium tiers very useful.

Final Thoughts

Loom is a great, lightweight way to quickly record information and share it (even on the free plans). The premium features, like editing,make it worth the investment (especially if you use other Atlassian products). It’s definitely worth checking it out!

If you’re looking for a more in-depth look check out the video below:

Configuring Fields in Company & Team Projects | ACP-420 Jira Service Projects Study Session #7

This week we continued our exploration of configuration, focusing on issues/work items and request Types, and this is another area that project admins will have a split experience in. 

Team-Managed Projects

Team managed project admins can do basically anything they want in terms of issue type setup (note that technically there are only request Types in team managed). This is good for smaller teams, or in cases where a project is a one-off. Not having to go through a Jira admin and modify schemes (or add new ones) is a massive time-saver, and also frees up the Jira admins to handle bigger, more complex challenges. That said, it’s also a bad thing, as you might quickly end up with multiple team-managed projects floating around that all require administration… and due to how they work there’s no single way to manage them all.

Team managed project admins can, however, add new request Types at any time. This gives them a ton of flexibility to quickly spin up new request types on demand. They can also make any changes they want to the fields and workflow (well dig into these next week) they want to. This includes recording fields as displayed to the agent (the issue view) and the customer (request view). Company-managed project admins can do this as well, however, it is important to note that these are spread across different tabs (“Request Form” and “issue view”) in company-managed projects, but they’re on a single screen in a team-managed project.

Company-Managed Projects

Company managed project admins are much more limited in terms of what they can change. They can manage request types (including making new ones), but can't make new issue types, add fields, change screens or modify workflows. Also, any request type they create has to be linked to an underlying issue-type that’s available to the project (via the issue type scheme). This, in turn, limits the available fields to what’s connected to those issues types. This makes them entirely dependent on a Jira admin to help with updates. (Although they can't make these changes, understanding what is needed is very helpful as it makes it easier to file a request and work with a Jira admin to make those changes).

Company managed project admins can, however, control what fields are displayed on the request (as long as they're available on the underlying issues). They can also change the display name (what a customer sees) to make the experience a bit easier. They can also change the display name of workflow statuses, which seems like a small thing, but can have a bit impact on someone's experience.

Next week well pick up with emailed requests and then dig into knowledge bases and workflow setup!  After that there's a week break for TEAM25 (if you're going let me know, I'd love to connect there!).

Pages and Basic Editing - ACA-920 Confluence Essentials

Pages are the basic building block of Confluence and what many of us think of when we think of Confluence. They’re basically Word or Google docs and allow us to create a wide range of information that we can easily share with users.

Page Creation

An important thing to remember is that pages are created under whichever page you have open. This means if you make a page while you’re viewing the home page, it will get dropped at the bottom of the Hierarchy under the home page. If you make a page under one called “design” it will automatically become a child of Design.

This confused me for years…

And is why I don’t like that “+Create” button that’s at the top of everything! I find it much too easy to forget where I’m at and make a page under some random bit of content. That said, it does create the page. My preferred method is to use the “+” buttons in the Hierarchy as I know exactly where the new page is going (under the page I clicked the “+” next to.

Pages can be created in a few ways, but most commonly folks use the “Create+” button that’s clearly visible at the top of Confluence (and basically impossible to lose!). Personally this isn’t my favourite way of creating pages - mostly because when I started using Confluence I started using the “+” button in the Content Hierarchy… but also because it can be easy to “lose” a page when you create it this way.

Child Pages

A great feature of pages is they can be nested under other pages. This allows you to quickly organize content visually, making it much easier for folks to browse through what you’ve created. For example, you can nest all the “Policies” under the “Policy” page. This makes it easier for content creation (since folks know where to put something) and content consumers (since they can find stuff). There’s no known upper limit to the number of layers, but best practice is to limit this to no more than 4 levels to keep things manageable.

Editing Options

After you create a page you’ll see the editing menu, which includes a number of features to help you make content. One important thing to note is that you cannot change the font or text size! Instead, you can change the Text Style - mainly to various headers. I initially found it annoying that you can’t change fonts or sizes, however, it does simplify things (no more “serif” or “sans-serif” arguments!). Headers also serve an important function - they act as links on the page. This lets you easily hyperlink a specific header to someone, or, even better, connect it to various macros (we’ll dig into them more in a future session).

There are some other text options, like bold, italics, strikethrough and color that you can access, along with building lists and indents. The final section (“The good stuff”) contains options for things like adding hyperlinks (you can just CMD+V over text if you’ve copied a link to hyperlink it), insert images and attachments, and include things like layouts and emojis.

Templates

Templates are pre-formatted pages that make it much easier to quickly create (and consume!) content. Confluence comes preloaded with 140+, but Space Admins can also add and edit these to fit your specific needs. I highly recommend you review what templates you have, and then work with your Space Admin to modify as needed.

You can also search through templates, or easily browse with the categories - something I never knew!

Atlassian Intelligence

Atlassian Intelligence (or AI… see what they did there?) is included in Cloud Premium and higher and offers a number of different options to use AI to help improve writing and summarize pages. Personally I mainly use it to summarize things since I’m (sometimes) too lazy to read, but it does offer some great built-in options to leverage AI to speed things ups.

Wrap Up

Our next session is March 28th at 6 AM PDT and covers Advanced Editing- I look forward to seeing you there, and check out the recording from this session below!

Fields, Screens and Schemes - Oh My! ACP-420 Jira Service Projects #6

Schemes! I definitely tripped over my own tongue with this one... Issue type screen scheme is way too hard to say.

Beyond not being able to say them properly I personally find them incredibly confusing! Mainly this is because I have been a Jira admin before... This means my hands on skills are lacking. I picked up small amount here's and there as I worked with the Jira admins though, and event that little bit was incredibly useful. Even just understanding that schemes are a thing is helpful as it makes it easier to talk to someone else about updating the system.

That said, this means is I need to dedicate more time to studying this part of the exam than I do for others (check out the new acp-420 page for some things I'm doing to drill this in). I’ll also be spending some time mapping out how all these schemes relate to each other. I find that visually drawing things helps my mind keep them separate.

Schemes and Fields, Oh My!

Schemes, however, are very important for us to understand as they are the shared configurations in Jira. They allow us as admins to create specific settings and then apply them across projects. For example all of our support projects could share the same issue types, workflows, screens and fields. Then, when we need to update them we just update it nice and it applies everywhere.

Fields, while not a scheme, are where a lot of this starts. After all, when I think of Jira I immediately think of all the information I need to fill out. One thing to remember is that fields aren't directly applied to projects or issue types. Instead they're grouped into screens. These screens are then added to a screen scheme which can be applied across projects.

There’s also two flavours of fields:

1. System Fields - these are default in Jira and tend to be critical. Things like Summary, Description and Key fall into this bucket

2. Custom fields - These are fields you create

Most of the settings we’ll cover here show up under “Issues” under the Settings menu:

Schemes for projects

There's seven total schemes that impact projects, with issue type security schemes being optional.  Each of these let us control different aspects of the project.

• Notification Schemes

  Notification schemes allow you to define what notifications are sent out when and to who.

• Priority Schemes

  Priority schemes allow projects to have a different list of priorities. While this doesn’t seem like much it can have a huge impact on end users!

  Personally I find a lot of folks frustrated at having to use the same list of priorities as everyone else (it also tends to get long… and repetitive…). This scheme lets you break out different lists of priorities for different projects.

  It also applies to Team-managed projects!

• Screen Scheme

  These allow you to associate screens with an issue operation (e.g. view/edit/create). Basically they tell Jira which screen to use for those actions.

  For example, you might have one specific screen displayed when creating bugs, but a different one available when editing bugs.

• Permission Scheme

  This defines what permissions are provided to what individuals, groups or roles in a project. Setting this up helps ensure that similar projects get similar permissions, making a project admin’s job a lot easier.

  While the project admin can’t directly edit permissions they can assign roles, so ensure this is setup to support them!

• Issue Type Scheme

  This scheme defines the issue types available to a project.

  For example your Project Management projects could have Epic/Story/Subtask while your Support projects get Bug/Incident/Request.

• Field Configuration Scheme

  This scheme connects your field configurations (how a specific field behaves, e.g. hidden, required etc) to a specific issue type.

  For example the “priority” field could be hidden on Bug tickets by default, but displayed on Project tickets.

Schemes for Issues

Three schemes apply directly to issues. These allow us to control things like the workflow specific issue types fulfill.

• Field Configuration Scheme

  This scheme ties fields you’ve created to specific issue types. For example, you may have a “Symptom” field. In order to make it available to an issue you first have to add it to a Field Config scheme, and then tie that scheme to the issue type.

• Workflow Scheme

  This scheme controls the workflow a given issue type uses. For example, the Bug issue type may have a specific set of statuses it moves through, while the Story issue type has a completely different set.

  This workflow allows you to standardize the flow of specific issue types across projects.

• Issue Type Screen Scheme

  While the Screen Scheme associates screens with operations, the Issue Type Screen scheme associates them with issue types.

  For example you might have a Screen Scheme that contains specific fields for “Create” and then apply that to specific issue types via an Issue Type Screen Scheme. A different Issue Type Screen Scheme could apply different “Create” screens to other issue types.

But what about Project Admins?

Jira admins don't get to have all the fun though. Project admins can control the request screens by adding, removing, and managing fields that appear on request Types with is issue layout. This allows each project to choose what order fields are displayed in, what name is display to the customer and some other options. Giving this local control to project admins makes it much easier for them to handle day to day requests to improve their project.. although they still need to work with a Jira admin to add fields, change workflows and the like.

Each screen scheme gets one layout (which the project admin can manage) per project (something we need to keep in mind as Jira admins!). Project admins will be able to modify the “view” screen by adding, removing and reordering existing fields (but they can’t create new ones). Project admins can also hide empty fields, which can help clean things up for teams that don’t need every field in their project.

There is an important note in Atlassian’s training “Project admins can only add fields that exist in their project’s View screen configuration. If they remove a field from the issue layout, the field still exists in the View screen configuration. It just isn’t visible for that particular project.”

FAQ

1. What is a good way to name my schemes?

   1. It can get confusing quickly! There’s some different ways, but folks typcially rename the default to something like . Project key - type — example : ABC-SS for the ABC project Screen Scheme

2. How do I change priorities??

   1. There is a Priority Scheme that allows you to change priorities based on the scheme used.

3. What is the new name for “issue”?

   1. Work item… although I bet I’ll still call it “issue” for a while…
      

Permissions and Roles | ACP-420 Jira Service Projects

Aren't time changes fun? Apologies to the folks who missed any/all of session 5 due to the time change... Luckily we have about 6 months before we get to do it again! (recording below if you missed out!)

Session 5 dug into permissions and roles. Personally I have to handle questions related to these topics on a weekly (sometimes daily) basis, so they are close to my heart. This also takes up 14% of the exam (but feels like half of my day sometimes!).

Check out the info below for more about what we covered, including the FAQ that folks had.

• Before you start!

  Before we get into how they work, you'll want to consider why you need them. It's very easy to dig in and start building roles or schemes. Resist the urge! Instead, step back and talk to your team and stakeholders about what is needed. I start by understanding the types of people who will be using Jira. Examples include agents, auditors, managers and the like. This is essentially building your list of roles, which will be useful when you start building.

  Once you understand the groups you can determine what they need to do. For example, some groups may need the ability to respond to customers, while others should only be able to view tickets. This mapping process can feel arduous, but is an important step in understanding your teams needs.

  This can take a while, but at the end you'll have a blueprint of what you'll go build. This makes it much much easier since all you'll have to do is push the right buttons - all the hard part (the thinking) is already done.

• Permissions

  Permissions are layered, like an onion! On a day-to-day basis I regularly only interact with these at the Project level, however, as admins we need to understand what falls into each layer, and be ready to troubleshoot issues that can span levels.

  • Organization - At the top is the organization level. This layer control things like the ability to @mention, or access the instance.

  • Product - Next comes the product - e.g. Jira service management. This level mainly allows you to manage who can use the product in your org.

  • Project - Next is project level. This is where most folks will have access as it allows you to be a project admin. Here you can control things like roles, customer access and the like.

  • Issue - The last level is the issue layer. Typically I don't see this level being used as it adds more complexity and most of the time you don't need to lock issues. That said for environments with sensitive data (e.g. hr, finance etc) locking issues is important.

  While there aren't 'gotcha' type questions on Atlassian exams, we do need to be careful and understand nuances to access. For example, 'assignable' and 'assignee' are both required permissions to be assigned a ticket (the first allows you to be assigned to a ticket, the second allows you to assign a ticket). Nuances like that are important for the exam, but also as a an admin to support our teams.

  Some nuances we should keep in mind include:

  1. Jira Admins are determined by who has access to the “jira-admins-(sitename)” group, or assigning a user to the Jira Admin product admin role

  2. “browse users and groups” lets people @ mention users, select users from picker fields, share issues and see names. It does not prevent folks from assigning issues (I ran into this at work recently!)

  3. “Browse projects” is the most important permission (according to Atlassian! :D) as it determines who can see a project and issues… without it you can’t see anything, regardless of your other permissions.

  4. In order to edit due dates and rank issues you need both schedule issues AND Edit issues

  5. Service project agents only applies if you’re in JSM

  6. Some perms can be disabled globally like liking, watching and voting.

• Roles

  I think of roles as types of people that work in Jira. There are four roles that come with Jira, and we can't remove them - admin, agent, collaborator and customer.

  Confusingly team and company managed projects have different names for them…for example 'agent' in team managed and 'service desk member' in company managed.

  That said each role contains the appropriate permissions for those types of people. Agents, for example, can open and edit tickets. Collaborators can open, and post internal comments, but not edit.  As an admin in a team managed project you can edit roles, but jna team.managed project you can't (unless you happen to be a Jira admin too).

  We aren't, however, stuck with just the roles were given. We can create new ones. This may require a Jira admin, but once they're created project admins can assign them to people, which indirectly allows project admins to control permissions. These roles can be incredible useful in meeting needs of your team, which makes understanding what they need to do and why even more important.

Next week we'll get into, looking forward to seeing you there!

FAQs 

1. Why are roles name differently in Team and Company managed projects?

   1. I have no idea! It is a bit confusing though…

2. How can project admins manage permissions in Company-managed projects?

   1. They can indirectly manage permissions by assigning Roles. This is where it’s important to have a good relationship with your Jira admin so they can partner with you to build Roles that make sense for your team.

3. Why is “schedule issues” necessary to re-order issues on a backlog board?

   1. This is a great example of a non-intuitive thing we have to just know. From what I understand it has something to do with how Jira stores rank order information… does it make sense? not really… Do we need to know this to help folks? yup.

Check out the session recording here

Services, SLAs, and Permissions - ACP-420 Jira Service Projects study session #4

Study session 4 is in the books! We covered three topics (detailed below), and will pickup with permissions next week since we ran out of time.

Next Week (Session #5)

IMPORTANT - Daylight savings ends (or begins? Not 100% sure how this works) this weekend. Please double check the time as it may shift by an hour.

Session #5 will pickup where #4 left off with permissions. Then we’ll get into:

1. Roles

2. Adding agents and customers

3. Team-managed permissions

4. Issue types, fields, screens in Company-Managed projects

What did we cover

• Features

  Project admins are able to turn on/off individual features within a Jira service management project. For example, if your group doesn’t use Services, just click the rocker to disable it. This has a number of benefits, but mainly it won’t clutter up your screen and it won’t confuse users with things they don’t need.

  That said, it can be frustrating if something is missing and you don’t know why!

• Services

  Services are things your team provides or supports. Some examples include databases, APIs and servers. Services can be grouped into Tiers, with Tier 1 being the most critical, and Tier 4 being least critical (e.g. folks won’t realize it’s offline). Services can also be linked to other services, for example, your website may depend on an API to work.

  Adding services to Jira service management lets your team more easily manage them as they can easily see what services there are, what tickets impact which ones, and how they relate.

  For example if the website is offline, you can easily see it is dependent on a specific server, and what issues impact that server.

• Service Level Agreements (SLAs)

  Service Level Agreements (SLAs) are agreements teams with with h customer groups on how quickly something is addressed. For example you might agree an account reset should be done inside two hours, or a server outage will be worked on continuously until it's solved.

  Jira service management allows us to define any number of SLAs, each of which can have different goals and different time targets. The tickets impacted by any given SLA can be defined by JQL, which means basically any grouping of ticket can be targeted. Within that you can break down specific time targets (how long someone has to meet the goal).

  SLAs also contain conditions, or rules when they start, pause and stop running. Typically SLAs begin when a ticket is created, however, this can be tied to some actions (assignment, comment, etc). Pausing an SLA is useful when the team is blocked (commonly info this when I'm waiting for the customer to reply). Stopping an SLA typically happens when a ticket is closed, but could also happen when a specific status is met or action taken.

  Finally, SLAs have calendars, which tell it which day(s) and time (s) to be counting down and a group can have any number of calendars. For example your 'account' tickets may use a 9-5 calendar while your 'outage' tickets may use a 24/7 calendar.

  Regardless of your initial setup I highly recommend making time on a regular basis (e.g. quarterly) to review SLAs and ensure they still meet your needs.

• Permissions

  We didn't get all the way through permissions but I'd highly recommend spending extra time here. Not only do I think it will show up on the exam, it's a common problem I run into in 'the wild', so the more we understand about how permissions work, the easier we can make others lives.

  There's 4 levels of permission, org, product, project and issue.

  • Org - access to your orgs entire instance. Allows control of things like admin, @mentioning and others.

  • Product - ability to control access to a product (e.g. Jira service management)

  • Project - ability to manage and control a project. This is typically the highest level of access I've had and allows things like modifying request types, changing rules, and managing SLAs. 

  • Issue - it is possible to restrict access to issues. Typically I prefer not to do this as it complicates things, but it can be necessary (e.g. for HR tickets).

Study tip

Keep Jira up on another screen or yab and switch into it to practice as you study. This will help cement ideas and remember things better. 

FAQ

1. Do services have to be linked to a physical thing?

   1. No! Services can be a physical thing, like a server, but are also typically non-physical things like API, websites etc.

2.     What is camel case?

   1. A way to notate fields and other information without spaces. (many systems don't allow spaces in names). Typically the first letter is lower case, and the letters of new words are upper. Examples:

   2. jiraServiceManagement

   3. pronounceJQLLikeJayquill (ok, that ones silly)

3.    Can SLA's be tied to Issuetypes or just Request types?
   

   1. Either! SLA's can be tied to any filter you can describe with JQL - so you can define a JQL query to pull tickets by either request, or issue, type... or almost anything else.

4. Can you use Atlassian Intelligence to build SLAs?

   1. Not yet :(

5. Can we prepare ourselves in just a month for the exam?

   1. In general I wouldn't recommend it as there can be a lot to learn! That said, if you can dedicate a lot of time to studying, practicing and understanding this can be possible. Personally I like to take 2-3 months to prep, but others can go faster.

6.  Why am I limited to a single workflow per request type?

   1. On a technical level I believe Atlassian limited this to ensure tickets know which path to follow.

   2. On a process level this makes also makes sense as any give type of request should follow the same workflow - e.g. under what circumstance would a "password reset" require an entirely different set of statuses? If it does, it's likely a different request.

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.