Tips for organizing Jira project information on Confluence
Tempo Team
Originally published September 17, 2021
As organizations adopt a scaling agile philosophy such as the Scaled Agile Framework® (SAFe®), they'll have to review — and potentially revise — how they organize and share knowledge among teams. For companies that use Jira, that likely means taking a look at the way they organize their Confluence pages.
If you're unfamiliar with Confluence, it's a wiki-based knowledge repository that allows you to share information and collaborate. Its open principles are a great complement to Jira’s. With the ability to link Confluence pages to Jira issues, it is a common pairing in most companies with an Atlassian stack.
In the context of scaling agile, there are three questions worth exploring:
Which higher-level parts of your strategy and hierarchy belong in Confluence pages as opposed to Jira issues?
How should you link relevant Confluence-based information to the right Jira issues — so your team can easily find it?
How can we use Confluence in other places to capture knowledge that would otherwise be lost?
What belongs in Confluence?
Jira issues are distinguished by a workflow status. The three immutable categories are “To Do” “In Progress” and “Done” — in other words, Jira issues are discrete items that run their course and are no longer relevant to ongoing work.
Certain higher-level pieces of information don’t fit that pattern. Your corporate strategy and strategic initiatives, or themes, don’t run through that type of lifecycle, for example. Requirements documents — such as ISO standards, style guides or user requirements — are another. Their description might change from time to time, but they don’t go away and you'll always need them. This information belongs on a Confluence page.
But merely creating these pages isn't enough. You have to make sure they're easy for people to find, especially as those people are at work on relevant issues. Organizing that information so the important stuff doesn't get lost can be a bit tricky. Linking the Confluence page to its related issue is a good standard practice, but there are a few details you need to iron out as you consider your strategy.
How to link back to issues
Linking to a high-level Confluence document, such as a corporate strategy page, doesn’t require a lot of careful planning. This type of information is commonly organized under a “Strategy” header at the top, with strategic themes as sub-headlines. Under that, you can finally see items that can be categorized as issues. Linking these items together puts everything in context for users. When they understand the bigger picture, it makes everyone’s job easier.
Something like a requirements document can be more complicated, however. Two common approaches exist for linking this information to issues to help your team access them; at the story level, and at the Jira epic level. Here there are a number of important considerations before you decide on an optimal strategy.
Duplication of effort - when multiple stories are tied to a certain requirements document, do you write the Confluence page to have a link to each story individually? Or do you just link to the stories’ parent? In our experience, it’s usually best to link to individual stories in order to be as clear as possible to users. Linking to the epic only makes sense when the majority of its stories need a reference to that document.
Consistency - As we just noted, we think it's often best to link to stories instead of epics. Regardless, you should pick one strategy (linking to epics versus linking to stories) and stick with it every time you link Jira issues to a Confluence page. That way, users don't get confused about which pages to reference as they work. You might also consider linking docs that are broadly applicable to epics, and more topic-specific ones to stories. As long as you apply your rules consistently, it should work just fine.
Efficiency - Using the Jira Issue Macro, you can automatically create links between a Confluence page and its related Jira issues — a two-way path that embeds the Confluence link within the issue, and the issue link within its related Confluence page. (By contrast, simply copy/pasting a Confluence link in a Jira issue does not update the Confluence page, leaving the Confluence user searching around to find any related Jira issues). When editing in Confluence, find the macro by going to the "+" drop-down and selecting "Jira Issue/Filter."
Information warehousing - Some types of information need to be accessed so regularly that links to specific issues are superfluous. For example, if your graphics department needs to frequently reference an in-house style guide, there's no need to bother linking it to their issues. It should be understood that the style guide (or whatever the document may be) is a continuous point of reference.
How can we use Confluence in other contexts?
Finally, we have some other strategies for collecting and sharing information within teams using Confluence. They fall into two main categories: collecting information and reporting information.
Collecting: During the execution of a SAFe program increment (PI) for example, you can link to a Confluence page directly from the spot where your teams are working in order to gather feedback during the process. The link will not be in the way and will provide a quick, real-time method for collecting users’ thoughts and ideas. This allows you to collect feedback that might otherwise be missed.
Reporting: Because of the aforementioned integrations with Jira, you can post a variety of information in Confluence that may be of interest to leadership. Through macros you can create diagrams, charts, and even full work breakdown structures that show real-time information and updates. (Be mindful that the user looking at data would need the correct permissions on both Confluence and Jira).
Plenty of organizations using Jira use Confluence, too. Leveraging their integration and capabilities will allow for a result that is greater than the sum of its parts. Whether you are storing information for your team to use or sharing information about the state of that work, Confluence can be a big help.
A growing list of companies are using Structure as they scale agile — read some customer stories to find out more.
Sign up for a demo
Register
