How to Write a User Story ?

Ah, stories… Dev team complains they are not enough specified, Product Owner complains he doesn’t have time to write them and Scrum Master complains they are a meaningless mess. But writing a story should not takes than much time and it doesn’t have to be detailed to be clear. Let’s see how to be efficient in writing stories and see some good and bad examples.

A story tells a story

First, goal of a stories is to synthesize a user’s need. It should create empathy so that developers understand how they can help user. So a story should tells a story. It should contains a protagonist who aspires to a goal. And to reach this goal, he needs something from you, he require your help. You are the support. You are the Sam Gamgie that will help Frodo throwing that damn ring into Mount Doom. So a good story should contains a protagonist, a need and a goal. And a very good way to always have these 3 points is using the famous:

As a [protagonist], I need [something] in order to [achieve a goal].

I really hated this phrase at the beginning of my career because I didn’t understood the important part was not its structure “As a … I need … in order to …”, but the 3 points we just discussed before. Lets analyze them more in details:

The protagonist

A lot of stories start with “As a user”. That’s the worst way of starting a story because it gives no information. Anyone using your code is a user, including yourself. Imagine starting a tales by “Once upon a time, in a place, lived a character.”… That’s the case for any single story told since the beginning of mankind, so try to be more specific.

In our stories, protagonist can be:

An identified customer:
– As Renault Truck, …
– As Walmart, …
– As GE Aviation, …

A persona:
– As portal administrator, …
– As front-end developer, …
– As game artist, …

Or even an identified team if you are developing internal tools:
– As Kernel team, …
– As Marketing team, …
– As ML team, …

The need

The need should be expressed from protagonist point of view, and not from developper’s point of view. Don’t write “update library version” but “be compatible with new hardware”. Don’t write “Integrate elasticsearch” but “have search bar in main page”. The technical solution will be decided by developers once they will have understood the need.

The goal

The goal gives context to dev team and let them understand the scope and criticize the need. Maybe you won’t be able to achieve your goal with just what you’re asking for ? Maybe you don’t need that at all to achieve your goal and there is a much simpler solution ?

Yes, I know, Gandalf could not asked this to the Eagles because of reasons, bla bla bla, but that’s not the subject. The subject here is that, if dev team know why they implement such and such feature, they won’t lose energy over-designing, they will be more inclined to propose a suitable solution, and maybe they will tell you “you can already do that”.

A story should be demonstrable

Last but not least, a Story should be demonstrable. As a developer, how can you prove you implement something ? As a QA, how do you validate new behavior is the expected one ? As a PO, how do you prove you add a new feature in your product ? As a team, how do you show the new feature during sprint review and get feedback from stakeholders ?

There are several ways to define acceptance criteria. You can write detailed specification that no one will read anyway, or you can use simpler format like “Given … When … Then …” or my favorite one: How to Demo. let’s see a small example.

As an administrator, I want to see the list of currently connected users to see who will be impacted by maintenance.

*How to Demo*

- Create a few fake user
- Go to Admin Page.
- Click on "Current Users" button
=> List of fakes users should be displayed

This small scenario gives us a LOT of information and questions:

• You need to populate database with fake data, or at least a dataset. Do you have one ? Are you able to create those fake data ?
• Go to Admin page. Does it already exist ?
• Click on “Current user” button. Do we have mockup for this button ?
• List of fakes users should be displayed. Do we have mockup for this list ?

So you can iterate on the story until it is ready, and avoid dev team working on it to discover in the middle of the sprint they lack half of the information.

This How to demo also tells to developers when to stop. If you don’t explain how to demo, dev team may be tempted to extrapolate and work on the maintenance part. Here, development ends when we have the list of connected users, we don’t care about maintenance operation, this is another topic.

Having an How to demo also tells to QA how it can validate the story. And finally, It gives the scenario to present to sprint review.

Example

To conclude, here are some bad and good examples.

Implement GPU picking

Acceptance criteria:
Picking should be done on GPU

As Airbus CAD team, I want picking on object to be more responsive in order to improve user experience

How to Demo:
Given attached data displayed in viewer
When I select objects
Then Selecting an object should not takes more than 500ms.

Example

As a user, I need to update CUDA to 11.4 in order to support new Ampere GPU.

How to Demo:
- Open properties in about dialog and show CUDA version
=> version should be 11.4

As IT department, I need application to support new Ampere GPU in order to move to new infrastructure.

Note: Ampere GPU require CUDA >=11.4

How to Demo:
- Deploy application on new infrastructure
- Load some data
=> Application should works correctly

- Execute test suite on new infrastructure
=> Test should be green

Example

As a User, I want elasticsearch in order to have a search bar

How to demo:
- Load main page
=> There should be a search bar (see attached mockup) 

As a buyer persona, I want to have a search bar in main page in order to search product by name

How to demo:
- Load main page
- search for product in search bar (see attached mockup)
=> corresponding products should display