Where should detailed product owner requirements be captured?

[Justin Dovidio]

If an Example of an Epic is…
      Epic: Product line X Web Section (New web section for new product line X)

And
An Example of a related user story within the product backlog is…
       User Story: User must be able to make suggestions for product line X

And
Example of related Task is…
     Task: Create new webpage and related database fields for Product Line X suggestions web section.

--------------------------------

If the Product Owner wanted to minimize static documentation and had the following Business requirements (not  intuitive to the developer) such as…

• Suggestion Description Field on webpage must have a max of 1,000 characters.
  Business Driver: We get many suggestions a day and only few resource to review… need user suggestions to be concise.
  
  
• User must check at least 1 product line X configuration type to which the suggestion relates.
  Business Driver: Past suggestions from users have been too vague and configuration type helps to clarify suggestion.
  • Configuration 12345 for product line A should not appear in check box selection list.

In Jira where is it best to capture the bullet points above.. should this be in the notes section of the user story? Should there be separate User Stories for each bullet point? Do most people have a separate document to capture this detail?

Thank you in advance.

[Luc Filion]

Hello Justin,

Maybe you're familiar with JIRA Text Formatting (https://jira.atlassian.com/secure/WikiRendererHelpAction.jspa?section=all) .

An extension to that is available as a plugin and would probably respond exactly to what you are looking for: https://marketplace.atlassian.com/plugins/com.topshelfsolution.simpletasklists

--

Personally, I would recommend that you track these as "Preliminary Requirements" (you create a new issue type - you decide the issue type name) and transform them to User Stories when they are accepted. This would ensure  JIRA Agile boards to render properly with the right information. You may also link them to Stories you create afterwards. 

If you intend to use Confluence (some clients may want documentation), I would recommend this Confluence macro that we provide to display more information about requirements and their associated links. https://marketplace.atlassian.com/plugins/ca.nuum.ajii

In any case Justin, please let us know here on this thread what you decide as your final solution - this will help us all !

Luc for Nuum Solutions.

[Anthony De Moss]

If you don't want to go the full confluence route (full license, another server, ..etc), but still need a place to document things, there is a separate wiki type product that is hosted right inside of JIRA.  

Linky:  https://marketplace.atlassian.com/plugins/com.topshelfsolution.simpletasklists

It doesn't have the same integration as confluence, in terms of associating pages with epics, and generating stories from within a page, ..etc. But it allows you quick creation of pages, tagging them, and easily mentioning the pages from within a ticket via a syntax similar to mentioning users.  

If you're fine with simple checkboxes, we just published a new plugin that allows you to create checkboxes (tasks) inline in ticket descriptions and comments. They are aggregated into a convenient list in the ticket itself.

Linky:  https://marketplace.atlassian.com/plugins/com.topshelfsolution.simplewiki

They are pretty lightweight and use a simple macro for creation. 

Hope that helps give you some ideas.

(Note: i'm the owner of both products, so If you have questions, feel free to reach out).

[Justin Dovidio]

Thank you Anthony, the products look very compelling. I am now "watching" simpletasklists... hope to see it on the cloud soon :)

[Yves Berquin [Matrix Requirements]]

If you are in a regulated environment, I suggest you use dedicated tool like Matrix Requirements' (Clouds or Medical).
The requirements should be linked to specifications, test cases, risk analysis. And if you want to link all these with a good traceability (are they all implemented? did I change a requirement and forgot to check if the tests are still valid? ...) there's just no way to do this in JIRA or Confluence.

You should however have a way to make links between these tools and JIRA for the tasks that need to be done to address the workload.

[Justin Dovidio]

Hi Yves, Thank you for your response. I am not in a regulated environment but I can appreciate the value that Matrix delivers. In this particular instance, I am a very detailed Product Owner looking to follow Agile best practices. Even though Matrix is geared towards regulated environments, I would consider using it in my case however, it doesn't seem to follow the Agile approach in terms of User Stories, Acceptance Criteria, DOD, etc. I would consider Acceptance Criteria as core to the overall Agile approach; I wonder if Acceptance Criteria functionality in Jira-Agile will be part of the next release?

[Justin Dovidio]

This is what I’ve been able to find out however, I will wait for a few comments from experienced users before closing the question.

It is recommended that detailed business requirements behind the User Stories are captured as Acceptance Criteria per Agile best practices (along with DOD).

Seemingly there are two ways in which you can choose to capture User Stories:

In both cases, you must ensure your Jira Agile project does NOT use the “Issue Type Scheme” of “TFP: Simple Issue Tracking” (which is set by default) but does use the traditional Agile type scheme.

Option 1
1. In Jira, ensure you have created related “Epics” for your project.
2. In Confluence, create a “Product requirements” Space.
    a. Ensure to populate the appropriate “Epic” in the field in the header template.
    b. Populate User Stories in the table provided (fund further below on the page). “Save” to exit Edit mode.
    c. Hover your curser over the User Story and there will be an option to create a related User Story in Jira.

Note. If you highlight all the cells in the row and click to add Jira User Story, it will concatenate (with no delimiters) all cells and pre-populate the same text in both the User Story and Description Fields. The information in the Jira User Story is NOT dynamic pulling from Confluence. There is no flag or indicator in Jira in the event that User Story information in Confluence is updated (it’s not good process to update User Story information after the fact, but it happens).

It would be time saving if you could set delimiters and (when highlighting all cells in Confluence User Story row) have only the #, Title, and User Story populated in the User Story field with Notes populated in the description field (or change default column value of Notes to Description to align with Jira).

Option 2
1. Simply create the User Story in Jira w/out use of Confluence.

Downside: I believe the downside to this option is that (it does not appear) you can have a single view of all User Stories and related detail in a document type form, the way in which it would appear and be viewed in confluence.

Upside: If for any reason the User Story Detail changes, the Assignee is notified.

All that said, getting back to the core of the question… there does not seem to be a “good” option for capturing Acceptance Criteria within the User Story which I would argue is hugely important.

You can add a Custom Field for Acceptance Criteria in the Jira User Story however, if you add Custom Field of type:

• Check boxes, the check box labels must be populated and remain static for all User Stories therefore, if you want to leverage check boxes they must be customized for each User Story… time/cost benefit is not there.
• (Blank) Multiple Lines of Text, it doesn't make it easy for the Assignee to indicate that the acceptance criteria has been met or to keep track for himself/herself which acceptance criteria has been completed and what is still pending in an unfinished User Story.

Additionally, if you use Option 1 above and add an additional column in Confluence to capture Acceptance Criteria, you will have to copy and paste the detail into the Jira User Story.

None of these options appear to be appealing. I am new to Confluence and Jira and very well may have missed some obvious options; I am willing and happy to be wrong and talked off the cliff.

Any feedback or comments are greatly appreciated.

[Joy_Mather]

wow - we are new to Confluence and have just integrated it to Jira. Our teams are currently just writing stories in Confluence and using the insert Jira link macro. I am about to ask one of BAs to test the above option 1.

[Luc Filion]

Joy, you will be really interested into this Confluence macro which is called JIRA "Advanced" Link macro - very useful for traceability. https://marketplace.atlassian.com/plugins/ca.nuum.ajii

[Joy_Mather]

Ok - I have been looking at this in my test environments but get unstuck on Option 1 C. Prerequisites met, there is no hover. I am on Confluence 5.6.6 and Jira 6.3.1. Do I need to upgrade before it will work?

[Alan Corey]

I believe Confluence handles this best.  We are about to look into it for the same reason and currently using the Description field and attachments to the JIRA ticket in the meantime.

[Justin Dovidio]

Thank you. I'd be grateful to learn what direction you end up taking to handle this.