Confluence (& Jira) like a pro

Did you know that Confluence and Jira integrate well together? Like “really really” well so that sometimes it feels like magic.?

I still remember the first time someone mentioned Jira. It sounded like they were talking about a secret weapon that would super charge our development process. It sounded like the answer to many problems.?

Half a year later, on a different project, I would get the chance to use Confluence and Jira. But despite that this project used this secret weapon of agile development, they had issues with documenting the features that needed to be implemented and making these easy to understand. It seemed that, these tools are only as good as what you put into them.?

I want to share with you what has worked for me. When to use Confluence, when to use Jira, how to learn to use these tools well together and a few of the pitfalls that I’ve seen teams make when using these tools.

In the beginning

Let’s go back for a moment to the mental picture of agile many of us have. The picture before Confluence and Jira that consists of the storyboard map of an application. It consists of rows and columns of post-its. Some of these post-its give name to bigger use cases, others to smaller use cases.?

Why I like this image? Because every post it has context. If you don’t quite understand what a given post-it is aiming for (it doesn’t have much text) you can look at it’s neighbours and try to figure out how the content of this post-it helps you take a step towards the bigger goal: building an app that makes something useful.

The storyboard, hanging on the wall, is also your project management instrument. As tickets are completed your team members write “Done” or “Won’t do” decreasing the number of use cases still to be implemented. The completed post-its don’t disappear, they stay there, in their place, giving context to the the post-its that are not implemented yet. By counting the completed and open post-its you get a sense of how much work lays ahead. By looking at groups of completed post-its you get a sense of what the application can do for the user today.

You can get this same experience with Confluence and Jira, if you use them in a specific way. A way that optimises for content and context. A way where Confluence is your storyboard hanging on the wall and Jira provides the tags “Done”, “Won’t do”, “To Do”.

The basics and the pitfalls

Jira is for task

I’ll say that again: Jira is for tasks. Once a task is done, it should disappear from your task list. This makes total sense, a completed task should not clutter your task list.?

What sometimes happens though, in the heat of the moment, is that we write important information in these tasks, information that will then disappear in a sea of completed tasks. It’s not lost, but it will take time to find the right Jira ticket and look in the right place within the ticket. Sometimes the information is in the comments, sometimes in the acceptance criteria or description. Tickets can get messy.?

It’s hard. A search for “product backlog refinement” shows diagrams like the one below that could be interpreted as suggesting that we create a Jira ticket to document our product. I’ve seen teams do their refinements with Jira open and work on the tickets. I’ve done this too! Or to say it differently, I have refined tickets as well.?

But we can do better.?

Confluence is your cookbook

Confluence is a wiki that is well integrated with Jira. A wiki (/?w?ki/ ( listen) WIK-ee) is a hypertext publication collaboratively edited and managed by its own audience, using a web browser (wikipedia). That definition doesn’t help much to understand when Confluence can help in the software development process, so let’s dig deeper.

I love cooking. When most of us want to make something new and delicious, we use a cookbook. A cookbook contains recipes which include the ingredients, the hardware needed, the steps to make the dish and a description of the end result, perhaps even a picture or two.

Confluence is your cookbook. There you document all the information you need to build a product.

Cookbooks don’t always make for great reading, especially the ones without pictures. That doesn’t mean your product documentations hast to follow that pattern.?Products solve problems and solving problems is exciting and nontrivial.

?In Confluence you document the problem you want to solve (the end result), the things you need to solve it (ingredients) and how you you plan to build (the steps). This can be done without pictures, but as we already established, that doesn’t make for a great recipe. So make sure you make it easy for readers to get interested, to build a mental map of the product, to see as much as possible of your yet to exist product. Add business process models, user flows, wireframes, mockups and storyboards. It will make for better reading.

You don’t have to do all this work on your own. Depending on your role within a team you work on a subset of these artefacts. For example, the product manager or product owner typically works on framing the problem and what kind of process and user experience would help the user. The team, the experts in building information systems, they bring ingredients to the table. They talk about how the user journey could be brought to life, by evaluating the parts?that might be needed and how to mix them together. The entire team collaborates in confluence and builds the content together.?

I argue, confluence is your best product backlog. That is where you should refine, in confluence.

Confluence (&Jira) like a pro

The first question you might have is: does that mean that I have to copy and paste documentation from Confluence into a Jira ticket?

No! Confluence lets you create tickets and directly connects them with the right piece of documentation. All you have to do is highlight some text and Confluence will give you the option to comment or create a Jira issue. You can select the project in which to create the ticket and the ticket type. If your stories, tasks, specification is stored in a table, you can even generate multiple tickets, one for every row in the table.?

When you create tickets this way, Confluence automagically adds a link to the ticket next to the story/task/requirement and the ticket is also linked to the Confluence page. This is fantastic, because now every piece of functionality on your Confluence page has more context than if it existed in a lone Jira ticket.

Now that we have the copy and paste discussion out of the way, this should save you a lot of time in artefact management. What else could you do to gain speed?

‘?’, The question mark is your friend. Both Confluence and Jira are web applications that were built for power users, they were built for speed. Shortcuts can help eliminate seconds of mouse motion required to press a button, to open a ticket or confluence page for editing. We’ll go through a few of the ones I find myself using the most.

‘e’ for editing. If you are on a confluence page and press ‘e’, if you have editing rights, the page will go into editing mode. No more having to press the “edit button”. If you are in the backlog and have a ticket selected and press ‘e’, the ticket opens up in editing mode. In Confluence you can save with a shortcut as well by pressing Ctrl + s (Windows) or command + s (Mac).

‘.’ For editing a specific field of a ticket when the ticket is open. For example, if a ticket has not been estimated jet, the story point field is not visible. By pressing ‘.’ You bring up a prompt that lets you type and search for a specific field and edit it on the spot without having to open the entire ticket in edit mode.

‘[‘ for opening and closing the navigation bar on the left of both Confluence and Jira. Sometime it just gets in the way and this is a very fast way to move it out of the way and bring it back when you need it.

Ctrl (Windows) or?command (Mac) +?[0, 2…4] to add a header in Confluence. When editing text, one thing that steels a lot of time is formatting headers by yourself. By this I mean setting the font size and making the text bold. Most text editors provide preset settings for different headers. Confluence is no different. For example, Ctrl + 2 will set the formatting to a H2, Ctrl + 3 to an H3 and Ctrl + 4 to an H4. If you want to format the text as a paragraph, Ctrl + 0. One important benefit of using headers in your text is that you can add an index to your page almost for free with?the index macro. And adding macros also uses a short cut.

‘{‘ to add a Macro in Confluence. This one is very helpful, because adding an index of the page becomes { + “Inhalt” and adding a Gliffy becomes { + Gliffy.?

Wrap up

If you did not know about these features, you are more powerful know. Here are three highlights:

1. You learned six shortcuts are very powerful and will save you time.?
2. Using confluence to build and refine your documentation as a team is rewarding and saves developer time if you create issues from confluence. Your developers will always know where the latest documentation can be found. Plus it makes for better documentation when you have diagrams and context, both of which are easier to create and consume in Confluence than in Jira.
3. Lastly, creating Jira tickets directly from Confluence can greatly improve you product refinements and reduce you artefact hygiene.

Here is a last image I want to leave you to think about. I saw this years ago in a Ted talk by?Ursus Wehrli. Confluence lets you make the big picture visible, Jira lets you organise the building of that vision.