Agile User Story: How to manage in JIRA and Confluence

  • Post author:
  • Post category:Blog
  • Post comments:0 Comments
  • Reading time:5 mins read

What is a User Story?

Around the web, we found a lot of user story definitions.

“A user story is an informal, general explanation of a software feature written from the perspective of the end-user. Its purpose is to articulate how a software feature will provide value to the customer” – said by Atlassian

“User stories are short, simple descriptions of a feature told from the perspective of the person who desires the new capability, usually a user or customer of the system” – said by Mike Cohn

That means a user story is a simple description that is written from the perspective of the end-user. That is a non-technical language that tells the development team the context and reason they are working for

  • Who are they serving for?
  • What are they building?
  • Why are they building?
  • What are the values they are creating for the user?

Therefore, we have some format for writing user stories

User Story format

User stories are expressed by a simple sentence

As a <persona | type of user | role | who wants to accomplish something>

I want to <performing some tasks | what they want to accomplish>

So that I can <some goal | why they want to accomplish that thing>”


“As a bank user, I want to withdraw money from an ATM, So that I’m not constrained by opening hours or lines at the teller”

The question is “Is that format is enough?”?

With this simple sentence, the development might not know how to verify that what they built is satisfied with what the end-user desired.

Therefore, a user story template should also include conditions of satisfaction — or acceptance criteria — that clarify the desired outcome. This information helps the development team understand how to build the functionality and test that it meets the end user’s expectations.

The conditions of satisfaction format or acceptance criteria should be:

Given that <some context | how things begin>,

when <some action is carried out | action taken>,

then <a set of observable outcomes should occur | outcome of taking action>”


“Given that the user has logged in and selected the withdrawal option

When the user submits the available amount button and their balance is enough

Then money will be withdrawn and the account balance will be updated.”

Therefore, a complete user story format should be

How to manage User Story in a real-life

One of the common questions is “Do user stories replace a requirement document?” How the development team can write and manage user stories in complex software?

With the format above, a user story describes the language of business users. To describe a big software only business user language is not enough. We might need a technical language that tells the development how the functionality looks like (UI/UX design)?, how the system interacts with the user (flow diagram)? what are data fields? how does the system validate inputs from the user? What are error messages displayed for end-users in case there was a mistake? Etc…

Therefore only the user story format above is not enough. it’s often to write a real requirement somewhere and reference to the user story. That will meet both purposes of writing from the perspective of the end-user while providing enough information needed for the development team can build the feature.

Normally, a user story should be written using JIRA as in the picture below. That will help the team and customer have a quick look at the purpose of the user story and easier to keep tracking development progress by the JIRA workflow feature.

On the other side, a real requirement document should be written on a Confluence page. That will be easier for the development team to read and navigate the system document in a structured and detailed way. We can use the integration feature between the JIRA and Confluence to link the user story with the detailed requirement document. A Confluence page that describes a detailed requirement for a user story might look like as the picture below:

When a JIRA item has been linked on the Confluence page, we will see the linked section in the JIRA item as well. That will be easy for the team to navigate content between JIRA and Confluence.

Hope this helps!

Leave a Reply