How to Write Great User Stories

Wherever I go or whoever I speak about product development, one of the main challenge is defining the requirements. And if you are in a group that applies agile development, you'll probably hear at least one of these:

These are not mentioned in the task?! I cannot do anything. -_-
In the acceptance criteria, you didn't mention that you don't expect any bug from this development…
I guess we can mark task done because performance expectations are not clear in the task.
Are you sure this task is a sub-task? It sounds like an EPIC to me…

Do they sound familiar?

What’s a User Story?

So, what's this user story? A quotation from Mountain Goat Software company describes it in a simple way:

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. They typically follow a simple template:

Let me describe it by my own words too. User stories are representatives of product scope and requirements in micro level. But it's important to understand a user story does not represent a product requirement. It's much better than a PRD (product requirement document) since user story creates requirements with more details and focus on acceptance criteria even on small functions.

Unfortunately I have met few product management professionals who were describing it as a mandatory job in the agile development. However, it's there just to create crystal clear product scope, requirements and steps for each stakeholder.

Besides the fact of helping development teams to understand requirements, they are resourceful for planning as they help to make estimations on timing and/or effort.

Be Precise!

User stories can be risky as you use a verbal communication and chosen words can be imprecise. Always try to use a common and understandable language with team. And let everyone in the team read what's asked in both grooming and planning sessions. It's critic to prevent team interpret your statement(s) in a different way.


  • In admin panel, user requires a dashboard of in-app campaigns or push campaigns and total conversion rates.
  • What product owner wants: a dashboard for "in-app campaigns" or "push campaigns and their total conversion rates"
  • What engineer understands: a dashboard for "in-app campaigns or push campaigns" and "their total conversion rates"

It's not a secret, give some details

Team and each stakeholders have to see details pretty clear to understand and pay attention to the persona. Each person should understand followings just by reading it.

  • To whom are we building this?
  • Who is requiring this? (Not task reporter, but feature owner)
  • What are we going to build for this?
  • Why are we going to build this?

Let's work on a generic (which I don't like) user story format. It has three sections where you define who wants, what is asked and the result.

As __________, I want __________. So that, __________.

As Operational Account Manager, I want to add tags for each campaign and be able to search them. So that, my clients can easily search and filter campaigns with respect to pre-defined tags.

But please always keep in mind that user story is not just "As __, I want __. So that, __." It must express the requirements, visualize the user journey, define needs and tell why you are going to do all those.

A user story must be aligned and supported with Acceptance Criteria (coming soon as it's described below!)

What's a Job Story?

We are talking about User Stories, now what's this Job Story? Job story format is my favorite and according to my experiences, it works much better than user story format.

User stories are easy to be manipulated since it does not fully explain the situation, scope and whether solution is solving an actual problem or not.

In user story our format is:

As __________, I want __________. So that, __________.

But I question all the time, is this format enough?

  • It should define the situation rather than telling who wants this feature
  • It should give a motivation to solve the pain or bring a gain to user and affected each stakeholder
  • It should be clearly defined who will benefit from this development

For job story, format is like:

When __________, X want __________. So that, Y __________.


When I login into a client's dashboard to check ongoing campaigns performance, I want to see a summary section that shows number of active campaigns with respect to each platform, their daily, weekly and monthly conversion rates. So that, account managers and client representatives will be able to see overall performance right after they logged into their dashboard.

Adding more info helps to refine a situation is always better and makes easier to have a solution. However, don't mix adding more description with adding more features into the user story! You just need to make requirement perfect.

Imagine you are with a friend, and she asks your help with one thing. Here's the conversation:

Friend: I want something to eat

You: Let's go to that new restaurant! They are best in this district.

F: I want something to eat and I'm in a rush

Y: Hmm, then let's get you a croissant from that bakery.

F: I want something to eat, I'm in a rush and I'm starving!

Y: Ok then, let's go to there to get you a noodle box. So you can eat while walking.

F: No… I want something to eat, I'm both starving and in a rush. Besides I will be carrying a bag so I can eat only with one hand. I should eat something suits on the go.

Y: Why didn't you say so? Ok, let's get some Döner for you!

The point of this unnecessary conversation in a post is showing how important you describe your pain. If your friend tells her every related information to you, it would be much easier to find a solution for her.

Acceptance Criteria

You finally defined the situation, provided what you are aiming to achieve. But writing crystal clear acceptance criteria helps both product owner and engineering team to

  • Prevent any further questions about task scope and requirements
  • Make it clear what's needed and how to test it
  • Being a owner of the feature as it's described completely
  • Stop all possible errors or bugs forecasted in the user (job) story.

Basically it helps developers know at what level they need to work and know when to stop adding more functionality. Team will also have a common understanding of the request. It's also helpful to define limits of the user story. Long story short it answers What not How.

ps: Acceptance Criteria and Stories must be applied to all EPICs too!

Well, acceptance criteria ideally may include 3 different sections:

  • Functional Criteria: "Client should see active and passive users at the same dashboard in the mobile dashboard."
  • Non-functional Criteria: "Save Campaign button should be prepared toofor AB test."
  • Performance Criteria: "With the new API algorithm, time for request per minute should be at least 20% faster than current one."

Use Cases

Last but not least, you should consider adding visualization of user journey. Sometimes, it's not clear testers or any stakeholder to understand how user will interact with this feature or fix.

It helps to everyone (including product owner) to see where user journey starts and ends. All paralel paths must be considered too. Thanks to understanding possible journey options, everyone will overview scope and requirements better and to review and build test scenarios.

To be honest, lately I stopped writing use cases since my job stories and acceptance criteria were always enough to visualize everything :)

I hope this "brief" helps you too to define your product requirements and user stories!

ps: I'm again sorry for all developers who had to read all my detailed and long user stories.