Atlassian Confluence is a mind-blowing tool for capturing information on a project. Its ergonomics and perks, such as macros, document organization and teamwork features, bring up new ways of organizing your teams, but this has already been discussed in a previous article (“The myth of the shared network drive” in French). Today we’re going to look at managing business and functional requirements and technical specifications in Confluence.

JIRA or Confluence ?

The answer is both. While JIRA is ideal for tasks, Confluence is better at capturing text and content.

The reason why we’d advise to keep all “change management” in JIRA is because you want to track all sprints, features, bug reports and requests of any kind with an “issue number.” They help track the origin, stakeholders, estimates and discussions about every change. One should however notice that an issue doesn’t give an overview of a project, unless you live in a flat world with only one dimension.

Documents resulting of activities such as early analysis, requirement gathering, design and customer interviews should be kept in Confluence. This is the knowledge base of your project: It is a picture of the current state of the documentation.

Atlassian already has integrations between the two products:

• In Confluence:
  • Create a new issue from selected text
  • Insert issue key
  • Insert a list of issues
  • Insert a JIRA board
  • See the list of linked issues at the top of the page
• In JIRA:
  • Link to a Confluence page

From Requirement Gathering to JIRA Issues

For the requirement gathering phase, the best practice is to initialize a space with subpages for customer interviews, contract negotiation and retroengineering artifacts, such as screenshots and cartography.

Step 1. Create a space to capture unstructured information

In the next iterations, you’ll start drawing the outline and painting between the lines of your project. Through iterations of refinement, you’ll soon create:

• Business Requirement Documents (BRD)
• Functional Specification Documents (FSD)
• Technical Specifications.

Requirement documents often have a similar layout: First a few screenshots or graphs, then tables of requirements. Here is an example.

Step 2. Iterate and define requirements. On this screenshot we use Requirement Yogi to manage requirement keys and the built-in JIRA integration to display JIRA issues.

Once everything is fully spec’ed out, it’s time to switch to JIRA. As you can see on the screenshot above, we’ve created an issue (“ZEN-2817”) for a single requirement. Most often you’ll want to create one development ticket for a topic. Agile methodologies say that the right size for a development ticket is the smallest work unit which adds value to the customer.

Step 3. Raise JIRA development tickets and link them to Confluence pages. If you use Requirement Yogi, list requirements rather than the Confluence page, this is especially useful for bug reports.

Next step: Keep track of your requirements

The number of requirements quickly grows as your product develops. Confluence is a generic collaboration platform. You want to get a tool so your team stays on top of the specifications. When you type “Requirements” in the Atlassian Marketplace, several solutions come up:

• RMsis for JIRA
• Requirement Yogi for Confluence
• Behave Pro for JIRA (OnDemand only)
• MatrixRequirement Cloud for JIRA (OnDemand only): Integration with a paid tool
• qTest Connector for JIRA (Test management): Integration with a paid tool
• Go2Group for JIRA (Test management)

Most solutions only target JIRA. The last two ones focus on testing and should not be overlooked.

The clear leading feature in requirement management is the traceability matrix. RMsis is the champion in this area, whose prices are in the range of $1500 for 15 users.

The traceability matrix isn’t the major feature

Unfortunately, only strict projects care enough to maintain a requirement traceability matrix. In the real world, most projects handle requirements on the fly in Confluence documents. We created Requirement Yogi, starting at $4/user, which helps you annotate an existing Confluence page to extract requirements.

Mid-size and bigger teams often have full-time analysts to categorize defects and analyze new features before they are developed. They constantly need to link to requirements in bug reports and in new features. Therefore it is important to define a unique reference for each requirement and be able to easily find it. Requirement Yogi helps you define unique requirement keys which stick to the pattern of your company:

Step 1. Quickly annotate documents with requirement keys. Make sure they are unique and fit the pattern of your company using Requirement Yogi.

Accelerate your development velocity by showing excerpts inline

Requirement Yogi keeps a unique link for each requirement. It is then possible to reference it from another page or from a JIRA issue. Developers can work faster thanks to the “excerpt” feature: They see an overview of the requirement by hovering over the link.

Developers can work faster when they see an overview of the requirement.

Manage customer sign-off

Beyond a few man-days, a contract must be signed and the are several validation steps with the detailed specifications. The sign-off process often happens by email or paper. Requirement Yogi helps you with this by letting you export all requirements in Excel. Of course you can search and show a subset of them.

Search for requirements and export them in Excel to attach them to a contract

See the documentation of Requirement Yogi for Confluence or the Atlassian Marketplace entry.

Agile or Waterfall ?

A common false misconception is “If you do Agile, you don’t write requirements.” Every project needs requirements at a different degree. Agile projects emphasize on staying lean, however there are many systems which need to be closely documented, notably APIs. Of course Agile projects usually do it in a more clever way such as state diagrams for database processes and schemas with annotations, but those rules always need to be referenced from other pages and tracked.

Of course traditional (Waterfall) projects will benefit the most of the integration between Confluence and JIRA. When components are tested, bugs can be raised with precise links to the proper section of the page, and business analysts can review their documents sequentially and check for full compliancy with the business rules.