
Blog
How to Manage Requirements with Atlassian Confluence and JIRA
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.
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.
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.
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.

Comments 9
Bob
When is Yogi going to be available for JIRA Cloud?
PlaySQL
Hi Bob, This is really not in the roadmap for the moment. We’re planning to make an integration with JIRA Server. There are too many difficulties with developing for JIRA Cloud for the moment.
Eric E. Snyder
Difficulties in implementation notwithstanding, I would like to see a cloud version as well. Consider this another vote in favor of the motion.
cody albert
Here’s another vote for Cloud. We don’t use the server version, but this looks perfect for us otherwise.
Anna
Where can i find a roadmap for the features?
PlaySQL
To be made aware of the release notes, please go to the product page on the Atlassian Marketplace and click “Watch this add-on”. If you want to be aware of probable new features in advance, you can check out our issue tracker: https://playsql.atlassian.net/issues/?filter=10400 .
Mike Drinkwater
Hi, can anyone point me in the direction of a simple guide to writing, stories, epics and bugs for Jira please??
Many thanks!
Mike
pat gustafson
We’re looking at moving our requirements database to a more jira friendly platform. We have a highly regulated product and thousands of existing requirements that need to be traced to development, test and issues. Yogi might be one. are there others?
thanks,
pat
PlaySQL
Hi Pat,
As a customer recently told me, “We’ve been writing requirements for 15 years, we’ve been using dozens of systems, from IBM RequisitePro to HP Quality Center to in-house software: You are the only one who understood what we needed”, referring to the system of annotating documents instead of asking users to copy-paste their specs into an Excel table. Another manager at this meeting added: “You are the only player in this area“.
Of course there are competitors. An excellent place to start is to browse the Atlassian Marketplace, see for yourself what are the features of the others, and look at their pricing. As a side note, you certainly know this customer, as it’s a famous international brand (I won’t tell you which because they might enjoy some privacy).
Best regards,
Adrien