Atlassian Confluence is one of the most widely used Wiki systems among software development teams. Besides other application areas it can be used to support requirements management (RM).

This article surveys relevant information resources and gives basic advice on RM with Confluence. It starts with Confluence-specific topics, touches the integration of Confluence with Atlassian JIRA, and concludes with recommendations on how to use Confluence for RM, also taking into account the inherent complexities of RM.

What is Confluence?

The Atlassian Confluence product homepage lists the main features of the tool and links to additional information. It positions the tool as a central work environment and structured information repository for teams, and for software teams in particular.

Atlassian’s central documentation homepage includes the links to the documentation pages of Confluence’s cloud and server product variants.

How to Use Confluence for Requirements?

For managing requirements, Confluence is superior to office applications, which are most commonly used as simple, entry-level solutions for requirements specification. Among Confluence’s advantages are:

• One central point of reference for all requirements, always up to date
• Version control of requirements changes
• Access control for viewing and eding requirements
• Some automation support for frequent RM tasks
• Collaboration support like automatic notification of team members upon changes

Atlassian, when positioning Confluence as an RM solution, focuses on the so-called Product Requirements Blueprint. This is a template page that ships with Confluence and that provides some basic automation for RM tasks.

The most relevant information resources from Atlassian on RM with Confluence are:

• Documentation page on Product Requirements Blueprint at the Atlassian documentation hub for its latest product version. The page shows how to create a new Confluence page using the Product Requirements Blueprint, and it outlines the main features of the blueprint template.
• Blog article “How to document product requirements in Confluence” explaining the use of the product requirements blueprint. This is an illustrative example of how to set up a page from the blueprint template, and how you can represent requirements and include UI designs.—Be aware that this example is very simplistic. See below for guidelines on more complex specifications.
• The example requirements specification page whose creation is described in the blog article is available as a separate picture file.
• An overview page on “Confluence for Software Teams” includes the link to the above blog article. It contains links to various additional topics like creating customer interview pages and release planning.
• The contents of the blog articles are also available as a PDF ebook titled “Software Team’s Guide to Confluence”.

Confluence and JIRA

The combination and integration of Confluence with its Atlassian sister tool JIRA provides particular advantages for RM, and for software team collaboration and project management in general: You gain coherent and consistent information management, task management, and progress monitoring across the entire application lifecycle and all software development workflows. In addition, there are various automation options around software change, configuration management, project planning, and monitoring.

Atlassian provides a documentation page on how to “Use JIRA applications and Confluence together”. It explains the prerequisites, lists the main integration options and use cases, and provides a summary table of the features and their required products, product variants, and version.

In summary, the main integration mechanisms for JIRA and Confluence are:

• Collect and display JIRA issues on a Confluence page
• Include reports and charts with information from JIRA into Confluence
• Easily create JIRA issues from text contained on Confluence pages
• Navigate from JIRA to Confluence and vice versa using links

Recommendations

Prefer Confluence over office applications

When you specify requirements mainly with office applications, text processors in particular, and already have Confluence in place, then you should consider to switch your software specifications to Confluence. Effort and risk of switching should be fairly small, and immediate gains and benefits very high.

However, keep in mind that every change in work practice and tooling requires some degree of planning, preparation, and guidance: Train and coach users, possibly provide page templates and usage conventions, and monitor how the Confluence spaces and pages develop.

If you, too, manage requirements with spreadsheet applications, you might consider to switch this part to JIRA. Information structuring and management in JIRA are similar to spreadsheets (as far as typical requirements tasks are concerned), and you gain benefits like versioning and integration with Confluence.

Prepare for requirements complexity

Requirements, like the software systems they specify, are inherently complex. Different persons or teams collaborating during requirements definition might have different or even incompatible work practices and documentation styles. No tool can dissolve this. You and your teams must face these challenges and manage them.

Take a look at Atlassian’s example Confluence page for requirements specification using their Product Requirements Blueprint: It is an excellent illustration of what the blueprint template provides for requirements specification. However, it is everything but a realistic specification document.

For instance, even the simplest software system has far more requirements than you want to put into one table on a Wiki page. Requirements belong to different aspects that you might want to separate into different specification documents—e.g., different functional dimensions or subsystems, or separating technical data requirements from user experience design. These specification parts interrelate: So, how do you capture and document dependencies? etc. etc.

Before you “just use” Confluence for requirements specification, consider questions like the following:

• What shall be the scope of specifications put into a Confluence space?—Everything in one space? Each customer variant of the system in a separate space? One space for each major product release?
• What shall be put into a single Confluence page?—Separate pages by functional groups? or by specification dimensions like functionality, legal, data, and user experience?
• How shall individual requirements be described?—As sections in a text flow? As table entries? What attributes / column shall the table have?
• Do we want predefined, detailed page templates?

Prepare to extend your requirements solution over time

Confluence is great for some kinds of requirements specification. But no tool can be suitable for everything. Be aware that you might gradually evolve and extend the ingredients of your requirements solution.

JIRA is a good companion of Confluence. You can add it quite easily even to ongoing projects, and you deepen the integration on the fly. At one point you might possibly switch the lead role between the tools. For instance, start ideation of a new system in Confluence; but when you are in implementation mode, then add new detailed requirements in JIRA.

It can also become necessary or beneficial to further extend the tool platform: There are specialized JIRA add-ons for requirements management. And you possibly need to integrate with other requirements or ALM solutions.

All this can become relevant, and you better should be prepared. However, as long as a simple solution works fine, keep it! Confluence can definitely be a fairly simple, stable, and very smart solution for many requirements tasks.