PRD documents

Agile Requirements Gathering

Using Confluence and JIRA to document the requirements of your project

By John Gordon

I’ll be honest, requirements gathering is not why I got into the software business. I got in software to code; it’s what I loved to do and what the client wanted, I thought.

I don’t think I’m unusual as far as developers go, we all love to code. An equally common trait in developers is that they don’t like to write requirements. I would also say that almost no one enjoys writing that huge, all-encompassing Product Requirements Doc (PRD). Creating a PRD requires a lot of effort–coordinating people’s busy schedules to sit in a room going over every facet of a product to be built in excruciating detail is a trying experience. PRD’s wouldn’t be so bad if all they did was take a lot of time. Here’s what else PRD’s are:

  • They expect you to know everything about a product up front. Why anyone would expect a document created at the start of a project to be an accurate represenation of the scope of work, when you know the least about what the project’s scope and complexity, is beyond me.
  • They become out of date before the digital ink has even dried
  • Cumbersome to update. Typically a PRD’s page count is higher than my great grandmother’s age. They’re written in PDF or Word format and weigh in on the Megabyte scale.
  • They’re difficult to share changes. Versions of a PRD are, more often than not, passed about via email, clogging your account and leaving you with that nagging doubt that you are in fact viewing the correct version.

The PRD is one of the key artifacts of the Waterfall Methodology. We think that Waterfall just doesn’t work for large projects. The Agile methodology started as an alternative to Waterfall. Many software teams breathed a sigh of relief when they read then Agile Methodology’s Manifesto:

…we have come to value…Working software over comprehensive documentation

Great! Adopt Agile and you can say goodbye to the PRD! While true, the PRD is not a product of the Agile process, you can’t get away from the fact that you still need to document the requirements of your project.

Agile requirements gathering

The Agile Manifesto created quite a stir. No more requirements docs? H’ray! Unfortunately, those who thought that Agile meant no requirements didn’t pay close enough attention to the manifesto. The manifesto states:

while there is value in the items on the right, we value the items on the left more.

While working software is more valuable than documentation, documentation is still valuable.

The Agile Manifesto wasn’t about getting rid of requirements, it stated there was value in documenting requirements. Agile just believes that creating a massive requirements document up front:

  • Is a waste of time because of the ever changing terrain of a project
  • De-emphasizes the need to have the developers and stakeholders hold conversations about what needs to get built

So, don’t think that Agile is about doing away with requirements, it’s really the case that Agile is about gathering requirements in the most efficient manner.

Agile requirements gathering’s main difference from traditional Waterfall is that it is done on an as-needed basis. An Agile team will only gather requirements for a feature just before that feature is ready to be worked on, gathering requirements throughout the product’s development. This is efficient because the team focuses on gathering the requirements that are needed; the team doesn’t waste time creating requirements for work that could be months away for the simple reason that, like a PRD, circumstances will change that will make those requirements obsolete.

Here’s what Agile Requirements Gathering Should Be:

  • Easy. The tools used have to make it easy to gather the requirements.
  • Collaborative. All team members play a part in gathering requirements. Product Owners identify the features and stories, and prioritize them, the developers, UX and QA team members ask the Product Owner questions to better understand the requirements, and the Scrum Master makes sure everyone follows the process in the most efficient manner.
  • Flexible. The terrain of your project will change as you develop it, make sure your map can be modified to accomodate these changes.
  • Remotable. The tools should work if your team is co-located or if they’re spread across distances. All members should be on an equal footing, able to access the latest and greatest docs.

After all this reasoning, it’s time to show how we use Confluence JIRA to accomplish the above.

Steps in Confluence

Confluence is a wiki tool at its core. It makes it very easy to create and edit content, and is perfectly suited to gathering requirements in an Agile manner. Step-by-step, we:

Create a “space” for the project

A Space is a Confluence term. It is like a wiki within a wiki. The Space allows you to restrict who can access it and customize the look and feel of that area of the wiki. All information for the project will be stored in this space. Documentation is worthless if people can’t access it in one place!

Create a requirements page

A requirements page maps directly to a product feature. Confluence has a number of “blueprints” (aka templates). The Requirements blueprint creates the skeleton of the feature’s requirements.

  • Meta-data about the requirements. Who contributed to it, what epic it is associated with in JIRA, etc.
  • A Confluence table for writing in the stories and their Condition of Satisfaction
  • A section for adding questions for the team to discuss
  • A section identifying the goal of the feature
  • A section to define what is out of the feature’s scope

As with any Confluence wiki page, there’s a comment section at the bottom.

Conduct a Product Owner grooming session

We are a professional services business and work with a large variety of clients, and most of these clients are unfamiliar with Agile practices. We have a meeting with the Product Owner on the client side to collaborate on identifying the stories that make up the feature and the stories’ Conditions of Satisfaction. Confluence is great for letting the team quickly enter the story summary, the story itself, its priority, and the conditions of satisfaction all in just one row of the Confluence grid. Entering stories is easy, even for Agile neophytes.

Product Owners will create their own requirements page and define the stories and conditions of satisfaction themselves eventually. Working with the Scrum Master, the stories, and the larger Conditions of Satisfaction can be added to JIRA.

Add the stories to JIRA

Confluence’s integration with JIRA is one of the big efficiency gains for us. Once the step of identifying the stories is done in the Confluence requirements page, you can highlight any text in the wiki page and instantly create a story in JIRA with the story’s description pre-filled and attached to the epic identified in the meta section of the Confluence requirements page. We typically highlight the brief summary of the story instead of the whole story text because this functionality only allows you to populate the summary field for the story. I’m hopeful the good folks at Atlassian can make it so you may add several fields of data at once eventually.

Highlight and hover to create a JIRA story

Clicking on the JIRA icon allows you to populate the story with the description and links it to the associated Epic in JIRA.

As Sally, I want to edit existing synonyms so I can address the capricious nature of English.

The requirements page in Confluence is handy for giving all interested parties a good understanding of what this feature is supposed to do. We’ve found that keeping all requirements information in the JIRA stories only wasn’t conducive to getting a big picture view of what it was we were trying to accomplish. Being able to see the requirements page put to rest a lot of concerns our clients had about running a project in an Agile fashion. We also use the JIRA link macro to show a dynamic list of all stories associated with the epic. The status of the stories in the list is automatically updated as they change in JIRA.

Integration from JIRA to Confluence

JIRA displays a link to the Epic’s requirements page in convenient locations, when viewing the Epic overview and in JIRA Agile’s planning mode. It’s simple for a JIRA user to click on these links to find out more about the feature, rather than having to click through a bunch of stories to find out the big picture.

Linguistics - Synonyms

And in planning view mode in JIRA Agile:

Linked Pages


Requirements don’t go away when you manage projects with Agile, but the way you gather them changes. Up front requirements gathering a la Waterfall is replaced by just-in-time requirements gathering, saving you a lot of time by not writing requirements for work scheduled in the future that will only be out of date as the project evolves. Confluence and JIRA are good tools for keeping requirements gathering flexible, easy, and collaborative.

Learn more

Work for us: