Requirements Management with Jira and Confluence

It is always amazing how many organizations still use Word and Excel to manage their requirements. At some point, however, in larger software projects you come to a point where the call for a dedicated tool for requirements management in the team becomes louder and louder.

However, the introduction of a requirements tool often involves a lot of effort. Existing tools can also be used excellently for the administration of requirements – according to the motto “Make more out of what you have”. Many companies now have a ticketing system and an enterprise wiki. Jira and Confluence from Atlassian are widespread here. Both tools can be used in combination very well for an integrated requirements management in agile projects. In this article I would like to describe what this can look like in practice.

A fool with a tool …

While structured analysis and documentation of software requirements has long been common practice in the aerospace and automotive industries, this is not necessarily a matter of course in other organisations involved in software development. This is especially true for organisations in which software development is not part of the core competence, but where the focus of the company lies in other areas (e.g. trade, production or other services).

However, since IT now permeates virtually all areas of daily life, these companies are also faced with the challenge of implementing large and complex software projects – either as in-house projects or via external service providers.

While in smaller software projects with few participants the requirements can perhaps be managed more or less unproblematically in a Word document or an Excel list, this approach reaches its limits with increasing project size. Limited multi-user capabilities, insufficient support for distributed teams, difficult versioning of requirements, and problems with search and filtering are just a few of the disadvantages.

In addition, the complicated traceability of requirement sources and changes, as well as the lack of integration into the development process, make life difficult for requirement managers who only work with Office tools.

On the other hand, dedicated RE tools often cause relatively high licensing costs, they entail not inconsiderable training costs and then have to be adapted to one’ s own processes. In addition, the functions of the tools are often not “exhausted” at all – in the figurative sense, you buy a Ferrari and drive it like a Trabi.

Use of ticketing systems for requirements management

But what do you do if you are tired of the disadvantages of pen & paper or office tools, but the purchase of an expensive RE tool is not necessarily justified?

This gap can be closed with the web-based applications Jira and Confluence, which you may already have in-house for the development process and project documentation anyway.  Jira and Confluence have become so widespread in the corporate environment that it is no longer necessary to introduce these tools. Nevertheless, I would like to briefly point out where the respective focal points of the tools as well as advantages and disadvantages lie in the context of requirements management.

Short introduction of Jira

Jira is a web-based application with which trouble ticketing and task management can be mapped in projects. It is mainly used in software development and enables the definition of own workflows, own process types and own input masks.

By default, Jira includes the Epic, Story and Bug process types for software development. A standard process in Jira has an ID, a title, a status, a description and the possibility to add screenshots or other attachments. There is also a comment function for each operation that allows users to add comments to the operation. In practice, however, this feature is often misused as a kind of “chat”. Instead of chatting directly with each other on open issues, the customer, project manager and developer sometimes play a cheerful Jira comment ping-pong.

However, Jira’s possibilities are usually more than sufficient for simple small feature additions or error messages. When it comes to more complex and extensive requirements, the use of Jira as the sole requirements tool reaches its limits at some point.

Excessive use of the comment feature and the “Add attachments” function can quickly lead to a fragmented display of information. This is especially true if requirements change frequently and comments or attachments with outdated knowledge are not removed from the process. The final state of the request is then usually difficult to recognize and developers and testers have to laboriously gather the current information.

The situation becomes particularly critical when additional information is needed to document the requirement in more detail (e.g. wireframes, use case procedures, acceptance criteria, process diagrams). Apart from using a wiki markdown language in the process description or comments or adding attachments, there is no way to do this.

Project experience has shown that this additional information is often needed to make requirements more understandable to the development team. For example, an extensive checkout process in the online shop of a DIY store with about 50 decisions can be presented much more clearly using a process model than a pure textual description. Another example is the discount calculation for a fashion online shop with a customer from Turkey. Due to the language barrier and the complexity of the calculations, extensive calculation scenarios were developed that served as the basis for the acceptance criteria of the corresponding user story. And in general, tables and wireframes are often more helpful than describing the input elements in individual requirements when defining input masks.

Since this additional information cannot be displayed clearly in Jira, it is not advisable to use Jira alone as a requirements engineering tool. Although Jira is helpful for managing requirements, it is not a documentation tool.

Use of Confluence for requirements documentation

Confluence, on the other hand, an enterprise wiki for communication and knowledge management in companies, is suitable for the documentation of requirements. This also web-based tool includes a WYSIWYG editor, as well as options for defining page templates, version comparison and restoring old versions. In addition, it is possible to store structures. Just like Jira, Confluence can be extended via the Atlassian Marketplace with a number of add-ons, e.g. a Word export.

However, Confluence also has some drawbacks when it comes to requirements management. Although Confluence has a rudimentary task management, it does not have a fully developed workflow engine. Furthermore, Confluence does not offer any real integration into the software development process. A tracing of requirements down to source code level is not possible and the planning process of agile teams is not supported.

Effective requirements management through a combination of tools

Confluence alone does not help us on the way to an effective and efficient requirements management. As so often in life, the principle “It’s the mix that makes the difference” applies here, because the combination of the two tools optimally shows their strengths.

It is important to establish a strict division of tasks between Jira and Confluence, as shown in Figure 1.

Each requirement or user story is represented by a process in Jira. If further information is necessary to understand the request, it is stored on a Confluence page belonging to the request. The link to this Confluence page is included in a user-defined attribute of the Jira process.

The Jira process runs through a special workflow during the backlog refinement (see Figure 2). Depending on the desired scope of traceability, the workflow can end with the release of the requirement for development or can be extended by the implementation of the requirement.

A workflow can be easily created and edited in Jira using the WYSIWYG workflow editor. The boxes in Figure 2 represent the status of the processes. Via a process statistics gadget for the Jira start page, you can see at a glance how many requirements are in a certain status. The mapping of the process status to a corresponding Kanban board in Jira is also quickly completed.

In order to make the link between a Jira process and the associated Confluence page bidirectionally navigable, the Jira process can be embedded in Confluence via an application link. Thus you can see from the documentation in which workflow status the requirement is at any time.

As a rule, the requirement or user story is used to derive development tasks during the planning process. This is where Jira comes to the front as a task management tool. The tasks can also be created in Jira as a process and linked to the requirement. Since Jira offers the possibility of integrating different version management systems, the requirement can also be traced up to the source code (see Figure 3). In which dedicated requirements management tool does one already have this possibility?

Limits of Requirements Management with Jira and Confluence

So Jira and Confluence do not have to shy away from the comparison with comprehensive requirements management tools. But even in combination, the two applications do not quite come close to their functional scope.

In Confluence, for example, no baselining of the entire documentation is currently possible. This can be desirable if you want to view the complete documentation at a certain point in time or even use it as a basis for further processing. Unfortunately, Confluence only versions the wiki pages at the individual page level. You can help yourself by exporting the entire Confluence area to PDF or Word format. In order to be able to continue working on the basis of this status, however, it would first have to be imported into Confluence again.

Bottom line

Those who can do without baselines or automatically generated tracing matrixes as standard features in agile projects and are fed up with Excel lists will find Jira and Confluence a proven and lightweight duo for requirements management. Jira is predestined for the maintenance of requirement attributes such as ID and title as well as the control of the requirement process, while extensive detailed information on the requirement can be displayed better and more clearly in Confluence.

Notes:

Kathrin Herrmann has published additional posts in the t2informatik Blog, including

t2informatik develops and modernises software as a service provider. Click here to learn more.