What's your company's work flow for inputing SW Requirements?

Before people mention Green Hopper (which we use), there is a slight nuance...


We have an internally installed instance of Confluence, and are using On-Demand versions of Jira and Green Hopper.

Our business teams have a myriad of ways of ways for tracking requirements... some still use excel, others list in confluence and don't input into Jira, others enter into Jira, tag as an enhancement and as a business req, and then manage in Green Hopper.

We briefly looked at Wikidsmart, but ruled that out as we're using on-demand versions of Jira and GreenHopper.

I'm bet there are a number of people who would like to share their "best practices" out there... any suggestions?



4 answers

1 accepted

3 votes
Accepted answer

There are probably infinite ways to do agile software requirments. On the Confluence dev team we use Confluence and Greenhopper extensively for planning and tracking requirmenets. When we're working on a new feature area, we'll create a requirements document inside Confluence using the Product Requirements Blueprint. This allows the PM to describe more intangible things like feature goals, strategic fit, UX thoughts, competitor examples, etc before they dive into the indiviual requirements and stories.

The requirements document goes through an informal review process where a PM, developer, design and QA engineer will review the document and give comments. Once everyone's had a chance to review and comment, we change the document status to "reviewed" and copy the stories into Greenhopper where we can estimate them and put them into weekly sprints (most teams use scrum). We also link the GH stories back to the individual stories in the Confluence requirements document using the JIRA macro so that anyone looking at the document can see the status of each story and click into the JIRA ticket if necessary. We also link the document to the Epic for traceability. (A requirements document typically maps directly to a Greenhopper epic.)

Then we plan our sprints and do our estimation. At the beginning of the sprint, we create a Confluence page for each sprint planning meeting so that we can track things like sprint goals, team leave, etc. At the end of the sprint we'll hold a retrospective and record the results in a Confluence page so that we can refer back to the conclusisions and recommendations and continually learn as a team.

Once all the stories on the requirements doc are implemented, we change the requirements doc status to "done." In the Requirments Blueprint Collector page we can then see a list of all the requirements and where they are in the review/implementation process.

My colleague also wrote a post about this very thing at http://blogs.atlassian.com/2013/07/agile-requirements-documentation/ which also has some great ideas and dicussion on this topic.

Thanks for the blog link! It's funny your colleague mentioning the dearth of PRDs. It's probably more applicable at larger companies, but I personally have evolved my PRDs to paint a bigger picture of the rapidly evolving competitive and industry landscape. I've found the developers and testers appreciate having someone keep a finger on the pulse of the industry in an easily digestible doc. I'll also insert customer quotes around key requirements.

When I get to the requirements section, I'm also creating corresponding jira issues, and then referencing (hyperlinking) those jira tockets within the doc. For the most part, our dev team works 100% out of Jira.

So why the PRD? It ends up being more of a customer validation/justification document (for me anyway) - helps move the resource allocation (we leverage shared development resources - capacity based model) process along.

Ultimately, one adapts to the confines of the organization. Just trying to find ways we can improve the flow... one step at a time. :)

First off, the combination of JIRA with GreenHopper and Confluence would benefit greatly in your software requirements gathering (since all of this can be integrated via Application Links). However, there is but one difficulty that you will face; which is the application links between JIRA OnDemand and your in-house Confluence could not be made due to the restricted platform of the OnDemand instance to allow external connectivity (see this Answers thread for more information on this regard).

This is my suggestion for applying the concept of software requirements gathering; it can be made with the above mentioned products if you have a practise like this:

  1. Whenever you have a new requirement, make sure that it is created in JIRA first.
  2. Create filters that is specific to a particular scope. This can include:
    1. specific product,
    2. specific issue type (Bugs, New Features, Task etc),
    3. specific tagged options (business requirement, enhancement etc)
  3. Create an application link that links JIRA and Confluence (remember, this would only work when you have an in-house JIRA instance, or added Confluence OnDemand in addition to your OnDemand products [application links would already be created when this is such]).
  4. I believe you already have a space in your Confluence to cater for specific products. In each of this space, create a JIRA Issue Macroto showcase the issues that pertains to the product in sections. For example:
    1. If your have product A, have specific pages for:
      1. Bugs
      2. Features and Enhancements
      3. Business Requirements
    2. In every of this page, input the JIRA Issues Macro and use a filter specfic to the section:
      1. For the Bugs page, show all issues from product A of issue type Bug.
      2. For the Features and Enhancements page, show all issues from product A of issue type New Feature or have the tag enhancement.
  5. Then, manage these issues in GreenHopper.

I feel that this is the best practise that I can imagine being an easier way to track requirements. If there's anything I left out, do add more information and we can see how we can proceed from here. :)

It depends with the team, but I personally do 1 - 4 as part of my daily flow (leveraging jiraissues macro to import Jira content into our confluence instance). As part of our requirements doc writing process, I do create the corresponding Jira issues, then reference the specific jira issue #'s along side the requirement so people can reference later on.

We'll update the Jira issue as the user story, ux, etc details evolve throughout the development process.

The big question at this point is whether to incorporate deeper ties using Greenhoper or some other 3rd party utility.

Justin, we really like the process you described and are looking to adopt it. Can you clarify how you structure your requirements in JIRA? Do requirements belong directly to specific projects or do you have a separate Requirements project that contains all requirements, then use some other method, such as labels, for mapping requirements to projects?

Actually, the idea of placing requirements, development tasks and testing tasks in one project would be the ideal outcome. On my previous job, we manage our sprints in the order of:

Requirements / Analysis > Development > Code Review > Testing > Documentation > Code Merge

The structure of this in the context of a JIRA issue would be:

- Bug/Enhancement/New Feature
|- Requirements / Analysis (Subtask)
|- Development (Subtask)
|- Code Review (Subtask)
|- Testing (Subtask)
|- Documentation (Subtask)
|- Merge to Repository (Subtask)

This way, we ensure that we track estimates accordingly and we have a breakdown on where effort is spent the most.

Hi Justin, thanks for your quick response! So to clarify, you recommend all requirements, development tasks, testing tasks, and so on that are part of a particular project should be owned by that project. In addition, you recommend having a "Master Issue", with the requirements, development, testing, ..., associated with that issue be structured as subtasks, which would allow easy requirements traceability all the way through the life cycle. Is that correct?

Thanks, Justin! :-)

Hi Justin, we are working on implementing this process and were wondering how you handled a few things:

  • How did you handle requirements entry by people that are not expert JIRA users? For example, if a member of the business development team wants to enter business requirements. For an inexperienced user, creating the master issue, then a requirements subtask of that issue is not so straightforward. We would like to provide an interface to these users that is as intuitive as possible.
  • Currently for Sub-tasks in JIRA On-Demand there are only two choices for the Issue Type (Subtask, Technical Task). Did you add more Issue Types to cover items 2-7 on your list?
  • Did every issue that you defined have all of the subtasks 2-7 associated with it? For example, if a testing task covered multiple requirements, how was that handled?

Thanks for your help!

It may help to know more about your environment and process. How many developers do you have? Are they co-located or offshore? Are you using Scrum or some sort of hybrid? Your question seems to imply you feel you need some sort of requirements document. Is this accurate? Why do you feel this way or why does your company have this as part of their process?

At my last two companies (current and prior), we abandoned traditional requirements documents when we adopted Scrum. Both companies had similar environments -- "small companies" -- 30+ developers, local and offshore, 3-5 Product Owners, 1-2 Scrum Masters. Separate business stakeholders that made requests of the engineering teams. In general a cooperative spirit where the business would request a "project" and the POs would flush out the details. There were review sessions but no "sign-off". Stakeholders would participate in Sprint reviews.

The stakeholder's requests would generally become Epics in Jira. The details would be flushed out as Stories by the PO. We use the Scrumboard to tie stories to Epics. Stories can be reviewed with the stakeholder online via Jira or exported to Excel or Word for review. (However, we made it clear that Jira was the "source of record".) Occasionally we miss having the holistic view a document and pictures provide, but again this can largely be met by exporting into Excel, and referring to UI wireframes or mockups. At least this has worked for the environments I've been in.

Cisco in general employs a mix of waterfall, agile, and hybrid design methodologies. It depends on the organization, type of development (end product), and historical/familiarity with various methodologies.

In order to attempt some level of integration between our On-Demand Jira instance and our internal Confluence instance is that we set up a specific user account in Jira, and leverage those credentials to pull content onto our confluence pages. Great for viewing issues... could be better for more interactive manipulation within Confluence (IMHO).

Suggest an answer

Log in or Sign up to answer
Community showcase
Published Jan 08, 2019 in Jira

How to Jira for designers

I’m a designer on the Jira team. For a long time, I’ve fielded questions from other designers about how they should be using Jira Software with their design team. I’ve also heard feedback from other ...

919 views 3 9
Read article

Atlassian User Groups

Connect with like-minded Atlassian users at free events near you!

Find a group

Connect with like-minded Atlassian users at free events near you!

Find my local user group

Unfortunately there are no AUG chapters near you at the moment.

Start an AUG

You're one step closer to meeting fellow Atlassian users at your local meet up. Learn more about AUGs

Groups near you