How to Write Good User Stories in JIRA for Software Delivery

Five useful components of a user story specification that facilitates the delivery of your solution


Jimmy Soh

2 years ago | 3 min read

Writing a useful user story can make a significant difference in your delivery timeline in the long run.

What is a user story?

In an agile delivery framework, a user story is the smallest unit of work to be delivered. The end deliverable should be able to demonstrate value to the user in the form of addressing the needs of the user specified in the user story; it’s essentially a user requirement that’s focused on the user’s experience.

What makes a good user story?

The way you write the user story would determine the outcome of the deliverable. Hence, it’s important to include the essential components in the form of specifications to the delivery team that will be building the solution based on the story.

Often, the user story is communicated to the agile team members via a software delivery tool e.g. JIRA. In my experience, the clearer the communication of the story, the less back and forth is required among the various stakeholders — which leads to efficient delivery.

A good user story would generally contain the following five components:

  1. User-centricity
  2. Background and context
  3. Screen flows
  4. Technical specifications
  5. Clear acceptance criteria

#1: User-centricity

The user story must provide some form of value to a specific user/group. By writing the story in the following format: “As a user, I want to be able to… so that I can…”, would help to ensure that the deliverables are tailored to the user and enable them to achieve their goals.

Sample by Author
Sample by Author

#2: Background and context

A brief background and context can help team members to understand the rationale of the requirement, which allows them to exercise discretionary decision making in times of uncertainty — reducing unnecessary clarifications with the stakeholders.

Sample by Author
Sample by Author

#3: Screen flows

I have found the sketches and mock screens the best way to align requirements among the various stakeholders from business users, designers, architects, and engineers — to ensure that everyone is on the same page and looking at the same picture.

Sample by Author
Sample by Author

The sketch need not be fully complete but should include the essential details i.e. input fields and layouts to facilitate technical solution design and documentation.

#4: Technical specifications

Similar to screen flows, technical diagrams and specifications provide team members with clarity on the deliverables.

Sample by Author
Sample by Author

There are many variations of technical specifications and documentation depending on the nature of your role and project.

For specifications on architecture-related and backend development projects e.g. cloud migrations, API/microservice development, etc. you may refer to my articles on drawing useful architecture diagrams and building quality applications for inspiration.

#5: Clear acceptance criteria

The acceptance criteria set the expectations of the deliverables. At the end of the sprint, the solution will be evaluated against these criteria to ensure that the stakeholders are satisfied. You may also refer to the several variations and types for acceptance criteria for inspiration.

Sample by Author
Sample by Author

How can I fail?

I have had my fair share of experiences with vague user stories whereby the contents of the user story only contained the user-centric story itself e.g. “As a user, I want to be able to…”

This has resulted in some of the following:

  • Developers making their own interpretations on the deliverables — which don’t usually go too well with the business users
  • Design inconsistencies e.g. different colour variations of “success” and “cancel” buttons
  • Testers being unclear on the requirements and success criteria of the user story — resulted in an increase in bugs and issues subsequently

The above has led to delays in the delivery timeline and down prioritising of important backlogs, which ultimately can lead to project failure.


The key takeaway is to provide as much clarity as possible in the user story for team members to act and deliver the work item.

As with my other articles, you can use these suggestions as a reference to create your own best practice — as practices can differ quite significantly across organisations due to each unique constraints; I’m just sharing what has worked for me. :)


Created by

Jimmy Soh

In perpetual beta—playing at the intersection between digital technology and business.







Related Articles