Stuff I'M Thinking About

To help you write better stories, here are some tips and tricks, using bad stories as examples.

Example #1

As a user
I want to click save
So I can save my work.

As a User

What user? I consider the term ‘user’ in a user story to be a bit lazy. The term has also taken on a pejorative flavour among many IT teams.

This can be improved by replacing the word user with something more specific. Some companies use a persona, others use a role. This line can also be improved by adding some context about the user’s current state.

I want to click save

This suggests a solution. User stories shouldn’t suggest a solution. It specifies that the user has to click something called ‘save’. Is save the best word? Why click?

So that I can save my work

Finally we have something useful in the story, suggesting what might be needed. The story is still missing the value that will be delivered to the user as a result of the thing happening.

Reworking the story to fix these problems we get:

As a writer working in a document
I want to save my work
So that I can come back to it later.

This version of the story is more specific about the type of user. It’s an external customer, who is a writer. We now know what part of our software they are using and what they are doing. This context helps anchor the rest of the story.

The second line provides what they want, while the third states what the value is that they get from the action.

The second line does raise a question though. The user wants their work saved, but that implies that the user has to save it. Let’s rewrite that line.

I want my work to be saved

This changes the nature of the feature from an action that the user has to take, leaving the implementation slightly more open.

The issues of how the item is saved could be resolved more clearly in the acceptance criteria for the story:

• My work is saved automatically every 30 seconds
• If I try to exit the document between automatic saves, I am prompted to save.

Or a more traditional UI:

• There is a ‘save’ button that saves the document when clicked
• If I try to exit the document between automatic saves.

There is also the given-when-then format for acceptance criteria.

Given that the user has an open document
When the document content has changed
Then the document is saved at 30 second intervals.

and

Given that the user has an open document
When the document content has changed since the last automatic save
Then the user is prompted to manually save their changes.

I prefer the shorter acceptance criteria in this case as I have already stated the user’s context in the user story.

Example #2

Add a button so that a spreadsheet of the data can be downloaded.

This is sometimes how stories get written. Someone thought, let’s just cut to the chase so the developers know what to build.

I’ll work through the process of converting this to a user story and see what we can learn anything in the process.

Who is the person who wants this feature? What are they doing at the point they want to download the data? What do they do with the data once it’s downloaded? What format should the data be in?

In this case it’s a researcher. They have just completed a search of a large data set, and they want to download the data from that search so they can manipulate it in Excel.

Converting that to a user story we get:

As a researcher
I want to download the raw data for a search I just ran
So that I can manipulate the data myself

To this we’d add some acceptance criteria:

• I have a way to initiate the download
• I am prompted to open the download in Excel

This does raise some further questions: What is the best way to initiate the download? Should it be a button or a link, and where should that be placed? What is the best text for the button/link. These are UX/UI problems that should be resolved before work starts, otherwise you may get just a link with some text that says ‘download’.

Further questions to ask are: What kind of manipulation do they do? Might this mean we are not showing enough information on the results screen, or perhaps the search is not giving the best results. How should the data be formatted? What is the optimal text size in the downloaded sheet? Would it be better to make the download CSV, a more open format? This details should be included in the acceptance criteria.

The purpose of a user story is to remove ambiguity, and provide clear direction as what needs to be delivered to the customer, and by implication, what does NOT need to be delivered.

The story as written could be delivered, but needs some clarification. I would also follow up later to find if there is anything that can be done to reduce or eliminate the need for a download altogether.

Example #3

As a user
I want to click on the title
So I can get more information about the item

This story is OK, but we can do a lot better.

As a user

There is no context for this story. You might assume that it is a search result, but it’s not clear.

I want to click on the title 

The title of what, and why click? Not everyone uses a mouse, in fact most people use a finger tap. Screen reader users use neither.

So I can get more information about the item

What is an item and why more information?

As a researcher who has just completed a search
I want to get more details on a specific item in the result
So I can get more information about that result

Some people will complain this is long-winded. I think it is an improvement because it gives a lot of context, and does not suggest any specific solution.

Let’s have another crack at it:

As a researcher who has just completed a search
I want to get more information about an item in the search results
So I can get more information about it

Marginally better, perhaps.

What about acceptance criteria:

• I can get more information on a specific result

Now, you could be specific:

• The title of each results can be clicked
• The link leads to the details page for the item.

Some Shortcuts

Most teams have a ‘definition of done’. This is a document that outlines some key things that are automatically in the acceptance criteria for every story. Examples of these criteria are:

• Tests have been added and passed
• The code has been reviewed and meets our standards
• There is documentation for the feature
• The feature follows the provided design

When not to use a user story

Bugs

Broken functionality should be reported with a bug reporting template. This does not have to be heavyweight, just covering what the user did, the result, and what was expected, along with any contextual information (browser version, time of day, direction of the wind, etc).

To give the developer additional context you could include (or link to) the original user story for the broken feature.

Quick Fixes

Fixing a typo, moving an out-of-alignment element on a page, and other minor changes don’t really require a user story. You can use acceptance criteria if you really want, but I think they are often redundant in those cases.

Example with acceptance criteria

Fix the alignment of ‘download’ button

• The button aligns with our grid system boundary (column3)
• The button vertical position is centred on the text to it’s left

You could include a screenshot of the fix as well.

Closing thoughts

The language you use in a user story is important. A story can imply things that are not intended, and can shape the solution is unintended ways.

Lack of clarity can result in the reader of the story making assumptions about the solution, while being too specific can limit the creativity of the team. 

The critical point of a user story is avoiding rework. Apart from any bugs, we don’t want to have to rework the feature if we can avoid it. Iteration is best done during the creation of the story, and during any UX and design work undertaken prior to the technical implementation of the feature. 

It is unrealistic, of course, to think you can get every feature perfect, and that no feature will ever need rework once it’s been shipped. We live in the real world. But improving the story, based on asking the right questions will certainly reduce the amount of rework.

Please use the comments to add any example of bad or good stories that you’ve come across, and include why you thought that.