Using Jira vs Confluence for User Story source of truth

[seesomethingelse]

Hi,

Currently we run our projects where we have User Stories and Acceptance criteria in Confluence, and Jira tickets are used to organise the implementation of these via Sprints and agile boards (and to log time via Tempo).

We're finding that:

• Documentation becomes stale very quickly in Confluence, because a lot of conversations and changes happen in Jira
• There is no one place to go and get an overview of the status of a feature or system since information is in both Jira and Confluence
• Adding new requirements or changes are painful
• Confluence User Story pages can become huge and you can get lost in all the detail that's thrown at you

We've started to do the following, in an effort to mitigate some of these issues:

• Have all User Stories and AC in Confluence, with a list of DoR and DoD against each one, so we can see where it is up to (Confluence is our source of truth)
• All requirement changes and additions are in Confluence, with Jira only being used to track implementation of the feature and to log time

This solves a lot of these problems however after some research I've found that a lot of places are doing the opposite of what we're doing where Confluence is used as just a list of User Story titles and have a link to a Jira ticket that has all of the meat (User Story, AC, status, conversation). There's even a blueprint in Confluence that drafts this (Product Requirements) for us.

I actually think this approach is better, but wanted to see what others are doing and how they find it?

Some issues with this approach that I haven't solved for yet:

• How do we handle changes to a US down the line when we've already closed off the ticket related to it?
• How do bugs fit into this?
• How do we track progress of feature implementation with this Product Requirements page?

Keen for any insights from anyone.

Cheers.

[Thomas Deiler]

Dear @seesomethingelse,

there will be no truth. However you will use the combination of Jira / Confluence is dependent on your current situation: Team size, subject working on, age of product, amount of stakeholders, ...

And

Individuals and interactions over processes and tools

(from agile manifesto)

It will not be the tool (and how it is configured)  that make you successful, its how all are  working together.

My personal recommendation is to write as less as possible inside tools. Use the tools more as a support for your brain (reminder, key words, specs) and discuss more with the individuals to keep it up in the mind.

How do we handle changes to a US down the line when we've already closed off the ticket related to it?

A user story tends, by definition, never to be done 100%. Otherwise you would have to document every single if-then-else. This wouldn't be agile anymore.

Try to differ between this "changes", either it is a new requirement or the the story was implemented wrong (probably its not a bug, but the requirements have changed).

How do bugs fit into this?

By definition, a bug is a not working functionality, described by an already accepted US. So raise it, prioritize it, fix it.

How do we track progress of feature implementation with this Product Requirements page?

Think about, if you really need this. Isn't just an Epic enough for tracking?

So long

Thomas

[Neil Root]

Hi @seesomethingelse

For context, I work at a larger financial enterprise organization with 85,000+ employees. 

I've witnessed a number of different teams using either Confluence or JIRA to contain the "meat" of the user story and personally I haven't yet identified if one or the other is a "best practice".  Generally speaking, I've seen many teams operate in the manner you are describing:

• Have all User Stories and AC in Confluence, with a list of DoR and DoD against each one, so we can see where it is up to (Confluence is our source of truth)
• All requirement changes and additions are in Confluence, with Jira only being used to track implementation of the feature and to log time

The teams I have been working on most recently have been operating the other way around, where PO/BA creates a Confluence page with their requested Product feature (EPIC), high-level requirements (acceptance criteria), a table of user story titles with short summaries and links to the corresponding JIRA issues which contain the "meat" of the story including a Summary, Pre/Post Conditions, Business Rules, Mock-Ups, Translations, Links to other Confluence pages with details relevant to the conversation, etc...
When requirements change to a particular feature or US after the previous JIRA ticket was closed, we simply open a new JIRA ticket to capture what needs to change moving forward. 

Regarding best practices...I believe the best approach will depend on what goals you are trying to achieve. 

Are you trying to capture all the relevant details of your conversations related to a particular product feature?

Are you attempting to leverage Confluence as living documentation for your product on an on-going basis?  ie, You want to know about a particular product feature and all the different work that has been done or is currently being done on this feature over time?

Are you using Confluence to manage requirements related to a future release?

Regarding your questions:

1. How do we handle changes to a US down the line when we've already closed off the ticket related to it?
   Recommendation: If the JIRA ticket was closed, then open a new JIRA ticket referencing the changes captured on the Confluence page. 
2. How do bugs fit into this?
   Recommendation: If bugs are identified after a release, open a BUG issue in JIRA in the backlog and have PO prioritize it according.  If bugs are identified during sprint, open a BUG-TASK (ie sub-task) associated to the US currently in the sprint. Manage accordingly.
3. How do we track progress of feature implementation with this Product Requirements page? 
   Recommendation: There is a way to insert a link to a JIRA issue (Could be either an EPIC or US) which will display the status of the ticket.  Once all the associated statuses are Done, the feature implementation is done. 

I'm also interested to hear from others regarding this topic to understand what strategies they use and identify any tips or best practices they implement to handle the challenges mentioned by the OP.

[Ronda Doris Ringo]

To me, it's not only about the team deciding on who is the quarterback, 'system of record', or source of truth like the original person posted.   But, most importantly, where is the best place for the BA (and Tester if you pick a requirements tool that can also provide for test case creation, runs, and traceability back to the user stories (or requirements.)  I work on short projects and large projects and often get paid for producing good deliverables.  If your story system of record cannot quickly generate deliverables and cannot keep versions of the stories from creation to baselined, you are already behind.  

Our approach is to use Jama Contour as the 'system of record' and when baselined by the customer, we synch the stories to JIRA.  The dev team takes over from there, plans their sprints, adds subtasks or whatever work needs to happen in order to move the story through the development and ultimately test process.  I have one team where the customer forced our BA's to use JIRA for management of user stories, and wait for it, Excel spreadsheets for test cases.  Generating deliverables is a nightmare.  Tracking numbers is worse.  And, the team spends more time performing herculean tasks to produce anything or conduct any reviews where are other teams get things done in record time.

Something to think about for newbies making tool selections. Let JIRA do what it does well. Pick another tool to help the front end side of a project.  Trust me. You won't regret it.

[Wendy.Isaacs]

This thread fills me with horror.  What happened to the good old days of agile principles like stories being a placeholder for a conversation, working software over comprehensive documentation, customer collaboration over contract negotiation.  Before Jira and Confluence we wrote story outlines and a bullet list of ac's on a record card which was thrown away at sprint end. 

What perceived problem or user need is being solved here?

Simpler times.