How to write a User Story, a programmer’s perspective - part 1

Photo: Stipula fountain pen

There are lots of online guides on what’s a user story and how to write a user story, just by writing “write user story” into Google you will get loads of useful results. The problem is that they just offer you the Agile perspective and completely miss one very important point - people misuse (or don’t know how to use) Agile.

In lots of companies I worked for, there was a widespread opinion that by using Agile, you don’t need product specifications and just a bare minimum of technical specifications because that “empowers the programmer”. But nothing could be further from the truth. That’s because sometimes product owners “hide” behind the idea of iterative development, using it as an excuse to not decide anything in advance and thus wasting time iterating over things that could’ve been decided before starting working on the story. Iterative development is a great thing, but only if you use it to improve between iterations, and not fill in the holes because the stuff was missing in previous iterations.

This guide will show you how to write a user story that will enable your team to implement it in the shortest possible time.

What’s a user story

Let’s start with a simple user story, written as most of those guides say you should, for a mobile app feature:

“As a user, I want to be able to login with Facebook.”

Although some of the guides for writing user stories consider motivation optional, we can easily see that in this case, motivation is crucial - that’s because logging in with Facebook is just the necessary precondition for all the social features we want to implement, so it would be wise to write them down.

“As a user, I want to be able to login with Facebook, so that I can share events with my friends and have my profile on all devices.”

This now is a bit clearer because the user’s motivation for logging in with Facebook is to not have to use other types of login (saves time), to escape creating profile (saves even more time) and to be able to share something with already existing Facebook friends (saves loads of time, but most people probably just wouldn’t do it). From the product perspective, by allowing users to login with Facebook, we gain lots of statistics we otherwise wouldn’t be able to have; we can also save lots of development time because we don’t have to implement our own user management features; we increase user acquisition because most people don’t want to register or create another profile. (NOTE: you should still implement the registration and profile creation because an increasing number of users value privacy)

Stories and epics

But if we examine this user story a bit closer, we can see that it’s not actually a user story, it’s really something else - an epic. Epics are rarely mentioned by the user story writing guides, and they are similar to user stories in the sense that they represent a feature, but it’s a feature that’s so big that it needs to be broken down into separate tasks (which will then be represented through user stories).

But when is a user story an epic? The rule of thumb is that a user story is an epic when the estimation for implementing is more than 13 or 20 i.e. when it would be surely more than one day of work and probably even two. Another rule of thumb that the user story is an epic (or that it should be split) is when the feature described is not atomic. If the separated tasks are independent, then they should be split into independent user stories; and if they are dependent, it’s an epic.

In this case, it’s an epic because we have a necessary feature (logging in with Facebook) without which other features cannot be implemented (sharing, Facebook profile). Depending on the tool you’re using for writing and sharing user stories with the team (and you should always use one!), creating an epic and tasks will be easy or not. Jira, for example, makes it pretty easy but the tool in general is confusing and hard to use. Trello, on the other hand, is simple and easy to use but only supports cards (TIP: but you can create a list that will be used for an epic, with cards for tasks and checklists for subtasks).

Divide et impera (divide and conquer)

Ok, so here’s what we have now - one epic:

“As a user, I want to be able to login with Facebook, so that I can share events with my friends and have my profile on all devices.”

with three tasks:

“As a user, I want to be able to login with Facebook."
“As a user, when logged in with Facebook, I want to share events with my friends.”
“As a user, when logged in with Facebook, I want to have my profile on all devices.”

Now that we have broken down the epic into separate tasks, it will be easier to write the acceptance criteria (i.e. criteria that need to be fulfilled for the user story to be considered finished) in the form of acceptance stories. It will also be easier to estimate the stories, and then the epic estimation will be simply the sum of all the task estimates.

Acceptance story

Acceptance criteria are usually written in the form of an acceptance story, that has every criteria on a separate line, using keywords Given, When, Then and And at the beginning. So starting with the first task above, it would be something like this:

User story:
“As a user, I want to be able to login with Facebook."
Acceptance story:
"Given I'm on the home screen,
And I'm not logged in with Facebook,
Then I see the 'Login With Facebook' button,
And I press the 'Login With Facebook' button,
And I login with my Facebook credentials,
Then I'm back on the home screen,
And the app shows that I'm logged in."

You can see now that what seemed like a simple user story has a not-that-short acceptance story, and it has shown us what’s missing in our user story so far that is necessary for the developer to actually implement this story:

  • we need the design for the home screen when the user is not logged in, that will have the “Login with Facebook” button
  • we need the design for the home screen for when the user is logged in
  • we need the technical parameters - when we log in with Facebook, we can then obtain the user’s Facebook ID, name, profile photo etc., but then we need to forward them to our server, and that call (with its request and response parameters) has to be documented somewhere
  • we haven’t covered any of the edge cases.

So what most guides and product owners would consider a pretty descriptive user story with acceptance criteria is still a long way away from being implementable by the developer.

In the next article, we’ll see how to cover the edge cases that we missed here so that our user story is ready for acceptance testing.