When working with Atlassian’s tools Confluence and JIRA, you might question where to put your requirements since both tools offer this functionality. At times, it seems the two are competing to accomplish the same task. Teams can find it confusing to decide which tool to use when both are available. This post provides the reader with the pros and cons of each approach.
For those unfamiliar with these Atlassian tools, Confluence is a content management like tool that allows users to create web pages that contain content, such as text, images, videos, etc. JIRA is a work management tool that stores epics, user stories, and tasks, along with their related workflows. The tools often run in parallel when used by teams. They have two different purposes but can share being a requirements repository. When comparing this capability, the real difference between the tools is that Confluence gives the user complete control over the structure and formatting, while JIRA provides a templated approach to managing work items which can be used to store requirements. In other words, Confluence allows the user total control, while JIRA is structured by Atlassian’s expert view of how to store data, with less flexibility to alter the structure of requirements.
With Confluence, you can place requirements in Confluence webpages. Confluence suggests that you use their Product Requirements Blueprint template to input your epics and user stories. Dan Radigan suggests this strategy in his post: “Creating a Lean, Mean, Requirements Machine,” where he lists Atlassian’s reasoning for using this approach. Their goal is to provide enough background for members of an agile team to gain an understanding of the context of the work. Any low-level design information is defined in user stories and linked back to Confluence using either the Confluence JIRA linking capabilities or JIRA Issues Macro control. This process works for Atlassian, but many teams have issues with the amount of detail that goes into the requirement pages in Confluence.
Another approach is to input all requirement information into JIRA and not use Confluence at all. In this case, epics and user stories are entered into JIRA solely. The epics and user story description fields contain all context and low-level design details. Many users consider this method a simpler approach because all work management information and requirements remain in one place. In JIRA, all requirements are in the same location where users manage the work. Therefore, they do not have to switch between Confluence and JIRA to see background and detail information along with epic and user story statuses. This user design is somewhat replicated in Confluence, as depicted below:
Notice how the inline details given by Confluence’s linking functionality provide information about the status of epics and user stories. However, the ability to view status information, while useful, is limited. For example, perhaps you would like to know who is working on a user story while in Confluence which would require you to click on the JIRA reference link to view this information in JIRA.
The JIRA approach is not without its issues, as using a single description field to store details can be difficult to manage. Imagine the user experience of scrolling through hundreds of lines of requirements. Since the structure of this information does not follow a defined format, requirements can be inputted in any ad-hoc format, making them hard to decipher and manage. JIRA does not offer an option for a structured description, although users have requested this functionality. Atlassian has yet to implement this capability. One can either try to add custom fields to mitigate this issue or use a JIRA plugin, but such solutions do not solve all concerns.
Both requirement platforms have their pros and cons. The choice to use one or the other is left to the team to decide. If the team prefers to have a structured approach with background context information, Confluence is a viable tool. If the team prefers to both manage work and view requirements in one location, they should choose JIRA. Both options will accomplish the same task and, ultimately, it is a matter of team preference.