The Anatomy of a User Story
Tell Me A (User) Story Part 2
In the first part of this series I outlined the INVEST formula and how it’s principles applied to the structure of User Stories. INVEST outlines the foundational structure that a User Story should adhere to, however it is an outline of what a User Story should aspire towards, not how it is written.
The detail of User Stories use a structured form of language that conforms to certain constraints. How this language is used and what questions it chooses to ask are fundamental to a successful story.
I tend to favour the behaviour driven approach to user stories, for me this allows the author to clearly define what is required while still leaving plenty of room for individual interpretation. This is in my mind the key to a good story, remove as much a ambiguity as you can around the required outcome without dictating how that outcome is to be achieved.
Quoting Dan North who developed the concept of Behaviour Driven Development:
It’s using examples to talk through how an application behaves… And having conversations about those examples.
The starting point of a User Story is the call to action or the statement of intent. What is the over-arching reason for this story, what is the single piece of value (the V of INVEST) this story represents. It is stated in a framed statement using the template of:
AS A stakeholder
I WANT to be able to do something
SO THAT a result can be achieved.
Like everything with the User Story format this statement can encapsulate a surprising amount of context, the ‘stakeholder’ can be something quite generic like ‘as a user’, more specific like ‘as a clinical pharmacist’ or ‘as a call centre operator’ or really focussed, for instance using personas characters with entire fictional backstories crafted to better represent actual users of the software.
The idea with this statement is to explain who the story is being delivered to, what needs to be delivered and what is the final outcome. It grounds the story in reality and gives it meaning, gives the developer a why? Hopefully building an empathy between the developer and the users in the process that stops the work being just an abstract problem to solve or mindless task to complete.
We’re not just developing a new reporting feature, we’re adding that feature for Debbie the Analyst because she’s spending 2 days of her week trying to hand crank a pivot table in Excel.
Even if Debbie is a construct it still gives the work a human face and impact.
It also forces the author to be specific about the outcome, I want this thing and I expect it to produce these measurable results. It’s important to remember it’s as much about failure as success, if a new feature does not produce what was expected then course correcting and analysis become easier if the original intention is clear.
The next part of the story is the laying out of the acceptance criteria, using the BDD format it will look something like this:
GIVEN a thing
WHEN something happens/an action is performed to that thing
THEN this outcome is expected
When writing the acceptance criteria I try to follow these rules:
It should be unambiguous, when complete I expect to this concrete behaviour to be present.
It should not define the solution, it’s an explanation of what finished looks like not how you got there. As such it should contain no mention of things like UI elements. Screenshot examples or wireframes should be kept to a minimum and away from acceptance criteria. The use of tables or other devices that obscure the clarity of the criteria should be avoided.
Individual Behaviours should be clearly called out with AND for related behaviours on separate lines, for instance:
THEN names should appear in alphabetical order by the surname and the surname should appear before the given name.
would be better expressed as:
THEN names should appear in alphabetical order by surname AND the surname should precede the given name.
It might seem pedantic but I’ve seen people miss everything after the ‘and’ on numerous occasions when it’s written on a single line, because their brains had only processed the first half of the sentence. There are some legitimate times where having things on one line is acceptable (like lists of properties) but if it’s a specific acceptance criteria it should be on a separate line.
To give an idea of this process let’s look at a hypothetical example.
Brie is an up and coming artist with a growing painting collection and fanbase, she has a site recently set up where people can purchase her paintings.
Brie started off mostly painting landscapes and her site was a simple gallery of her latest works, however she has expanded her repertoire to include other painting styles and the growing popularity of her YouTube tutorials means she now needs to add some features to the site to enable a visitor to find her paintings by category.
The site already has a basic CMS that allows you to upload a picture of the painting, its price and a brief description, they can be edited and deleted if needed. This story is simply to add categorisation and filtering.
Description
Due to an increase in content it is becoming harder for visitors to the site to find the paintings they are interested in. We believe adding categories to paintings and filtering by them will improve the user experience and increase sales of the paintings.
AS AN Aspiring Artist
I WOULD LIKE visitors to my site to be able to find paintings in a style
SO THAT people can find the paintings they like more easily
GIVEN that I have a painting to upload to the site
WHEN I add a painting
THEN I can give it a category Landscape, Portrait or Abstract
AND it may have only one category
GIVEN that I have a painting already uploaded to the site
WHEN I edit the painting
THEN I can change the category to a different one
AND the previous category is removed
GIVEN that I am a visitor to the site
WHEN I want to look for a type of painting
THEN I can find all paintings that belong to a specific category
AND they are ordered by the most recent first
Notice there is no mention of specific user actions (like clicking a button), we’ll go into more detail as to why that should be avoided later.
We’re also demonstrating a single piece of value by sticking to a hard coded list of categories, if we want to add the facility to add and edit categories that can come later once the feature has proved its initial value.
There might be some argument that this story is two pieces of value, adding categories and filtering by them. However if we look at this from the point of view of the user, categorising a picture does not present value until there is a facility for the user to gain something from it.
If there is a legitimate use for categories without using them for filtering, for instance making the categories visible with the paintings so a visitor can more easily see what type of painting it is, then a story to allow categories to be added without the filtering would be acceptable.
The yardstick we always use is the ‘6 month rule’. Essentially if I released the ability to add categories and then for some reason we couldn’t release filtering for another 6 months, would that be acceptable? If the answer is yes then split, if no then it represents a single piece of value.
User Story Anti-Patterns
So what goes wrong with stories? The format is not that complex but personally I’ve come across more bad than good.
Problem patterns arise for a variety of reasons. Often there is ignorance, someone enters a business or a role and is introduced to User Stories already written poorly and just adopts the style that surrounds them without questioning. Other times people struggle or can’t see a way of breaking work down into pieces of value and create malformed user stories of multiple value or split by technical concerns. Often times I don’t think people realise how important they are, they see them as the means to an end, just a way of telling the dev team what to do.
Whatever the reason a bad user story will be breaking one or more of the key principles of INVEST (discussed in part 1 of this article).
Solutions not Problems
Developers are often the worst people to write user stories, why? Because they think they have all the answers.
A user story is a ‘problem statement’ it is not a ‘solution statement’. It is not telling a developer what to do or how to think, it is telling the developer this is the next most important problem for you to go figure out because that is what you are paid all that money for.
Developers are bad at story writing because they like solving problems and as soon as they start to talk about the story they can often have a tendency to jump straight to the implementation. It can be really hard for them to not just write some cursory text simply as a placeholder for a solution they already have in mind.
These types of stories will often either have very specific details and reek of technical implementation, they’ll be really prescriptive and focus on the delivery not the definition of the problem, or they’ll be incredibly sparse and lack any detail (because the detail is in the developer in questions head).
The primary rule being broken here is the N of negotiation. Firstly who says the writer of the story has all the answers? The story writer may have a clear idea of what to do in their heads but who’s to say this isn’t flawed or just plain wrong. By turning the story into a series of commands you infantilise the developer(s) delivering the story, you remove their autonomy and turn them into a delivery system for the writers ideas.
I’ve seen this many times and have experienced it myself, if a piece of work is presented to you as a fully formed solution it’s almost impossible to see past that solution. Like Schrodinger and his cats, once the box has been opened then all other possibilities cease.
So here’s a subtle but concrete example of this:
AS A author of content
WHEN I receive an alert email telling me that a some content has failed validation
THEN I want to know what content has failed validation
AND why it has failed
GIVEN Content fails validation
WHEN an alert is generated
THEN the alert should contain the ID it relates to
AND The reason for the failure
The above is based on a real user story that was played on our backlog a little while ago. To give some context we have some legacy code that is still relied on by our newer software to supply it with some content, this legacy system is gradually being sunsetted using the delightfully named ‘strangulation pattern’ where a legacy system is gradually cut off and it’s features moved into a new system.
As we’ve built the new system we’ve used the opportunity to move some content validation that was managed by process to be managed by code. This means there are occasions where content authored in the old system might fail validation at the boundary of the new, we wanted a way of effectively allowing authors to know this had happened but we didn’t want to actively change the legacy code.
When this story was written it was off the back of some discussion of some potential implementation ideas which is why a subtle implementation detail crept into the story. Can you spot it?
WHEN I receive an alert email telling me that a some content has failed validation.
This may seem pedantic, do those two words really cause a problem? In this instance yes, those words caused a subtle shift in the story from ‘informing an author of a problem’ to ‘emailing an author of a problem’. If email turns out not to be the right answer do you carry on regardless? Do you ignore the criteria or go back to the PO for more discussion?
The developers who picked up the story ran into some unforeseen issues with the delivery and then started to dig a hole trying to deliver ‘the email story’ (because that’s what the story is telling them to do), when there were a few other easier options that could have been considered. It ended up causing delays, some backing out of code and the story probably took twice as long as it should of.
A better wording would have been:
WHEN I am informed that content has failed validation
Informed gives a clear intent of what’s require but leaves enough scope that the developers can consider multiple options, and if they change their mind during implementation they don’t need to re-write the story.
Horizontal Slices
This is a pernicious and all to common anti pattern. It often comes along side an Agile team that runs fixed sprints and is borne out of the idea of ridgid sprint goals and all stories completing in a sprint.
The team has a story that needs to be delivered and a velocity they want to maintain, the story looks too big to fit in one sprint or the team has a misplaced desire to stick religiously to Small of invest ‘can fit in an iteration’.
Stories often have obvious technical splits, frontend and backend, microservice one and microservice two, database and code. All of these combinations amount to splitting stories along technical lines (horizontal) as opposed to value (vertical). But why is this a bad idea?
If we look at our previous example and try to split it on technical lines:
GIVEN that I have a painting to upload to the site
WHEN I want to save the painting
THEN it is saved into a Category database
AND it’s category can be Landscape, Portrait or Impressionist
Followed by:
GIVEN that I have a painting to upload to the site
WHEN I add a painting
THEN I can give it a category Landscape, Portrait or Abstract
AND it may have only one category
AND it is saved to the category database
GIVEN that I have a painting already uploaded to the site
WHEN I edit the painting
THEN I can change the category to a different one
AND the change is saved in the category database
Followed by:
GIVEN that I am a visitor to the site
WHEN I want to look for a type of painting
THEN I can find all paintings that belong to a specific category
AND they are ordered by most recent first
So we have 3 small stories split by Database, Authoring pages and frontend visitor pages. All nice and short, each could fit each in an iteration and potentially multiple iterations. What is the problem with that?
Many, many problems. Firstly, these stories are not Atomic so they break the Independent rule of INVEST. They cannot be considered complete until all are done, how is a Product Owner (or equivalent) going to accept the database story? A developer showing him or her the new database is not sufficient.
Secondly can you spot the deliberate mistake in the categories? Now this is a stupidly simple example to bluntly make a point but it is a problem endemic in this approach. If the developer on the database can deliver a ‘finished’ story which hides a mistake that is only evident on the completion of other stories then you cannot legitimately say the story has been accepted.
Thirdly things like smoke tests and end to end behaviour can’t be seen in these stories until all of them are complete and mistakes are often not evident until the end. What this tends to cause is plenty of rework, either story churn (where stories bounce back and forth as problems highlighted in other stories and need correcting) or lots of small ‘stories’ that come in behind to correct mistakes. This just ends up adding time on top of development so that a seeming exercise in efficiency actually ends up achieving the opposite.
Fourthly this approach forces implementation detail into the story by it’s nature, what happens if the initial assumptions around the implementation are wrong? We’re back to the previous problem of fixing ideas to early and obscuring other potentially better possibilities, in Lean development they talk of ‘deferring commitment’ leaving decisions to ‘the last responsible moment’ a story should always open avenues of discussion not close them down.
Fifthly (I said there were many problems) it promotes a silo mentality, if you divide stories up in this way you tend to get little islands of development each building a piece of a puzzle but unable to see or understand the bigger picture. It tends to promote dev’s who are happy in their little corner of code but don’t know their system end to end.
A vertically sliced value based story forces you to address that, I put this in here and I expect it to come out over there, you can’t help but understand the system end to end in that instance.
I said in my previous article I will always choose Independent and Value over Small, small is there to protect against story bloat it is not unshakable commandment.
‘Thou shall not go past an iteration or face the Wrath of the Scrum Gods! May your goals fall to dust, your points be unknowable and your retros full of disagreement and woe!’
There is one caveat here, if there are genuine well defined software boundaries that provide an edge to develop against then stories with technical boundaries story makes sense.
So for instance if you have a react based web application and it’s fed by a microservice via an api that is managed by another team as a product in its own right, features are released and managed and your ‘frontend’ team develop against them.
In this case this isn’t about the technology it’s about the boundary, the api is a clear responsibility boundary so in that case measuring end to end value of a story from the api to the user through the front-end is still a vertical and is dictated more by team structure and separation of concerns than technology.
Stories Too Big
So the issues discussed above in horizontal slicing often come about because of this problem. New feature is needed, stories are discussed and written, sizing of story is MASSIVE, we’re agile we do small stories we need to split them, stories are split horizontally.
Most of the time this is because teams, developers and Product Owners, don’t know how to split stories by value. It can be hard and it is often made harder if stories are written in a solution focussed manner, if a story is written spelling out exactly how it should be implemented it’s almost impossible to know where to tease the value from it.
Instead if the story is spelling out the problem it makes it easier to look at it from different angles, what is it we’re trying to prove? What do we want to get out of it? And what is the simplest thing we could possibly do to achieve it?
An example of a story that is too big:
Description
Due to an increase in content it is becoming harder for visitors to the site to find the paintings they are interested in. We believe adding the ability to search paintings, add categories and filter by them and mark paintings as favourites will improve the user experience and increase sales of the paintings.
AS AN Aspiring Artist
I WOULD LIKE visitors to my site to find my painting more easily
SO THAT people can find the paintings they like quicker than they could previously
GIVEN that I have a painting to upload to the site
WHEN I add a painting
THEN I can give it a category Landscape, Portrait or Abstract
AND it may have only one category
GIVEN that I have a painting already uploaded to the site
WHEN I edit the painting
THEN I can change the category to a different one
AND remove the old one
GIVEN that I am a visitor to the site
WHEN I want to look for a type of painting
THEN I can find all paintings that belong to a specific category
AND they are ordered by most recent first
GIVEN that I am a visitor to the site
WHEN I want to look for a type of painting
THEN I can search for a painting by it’s title
AND I can search for a painting by it’s description
GIVEN that I am a visitor to the site
WHEN I find a picture I like
THEN I can indicate that the picture is a favourite
GIVEN that I am a visitor to the site
AND I have some picture I have marked as favourites
WHEN I want to look at my favourites
THEN I can see them listed by the date they were added
AND they are in descending order
Essentially there are three separate bits of value represented above text search, categories and favourites. If you wanted to go further you could say Text search on title, text search on description, categories, adding favourites, viewing favourites (this would depend on whether there was value in just adding a favourite without being able to get to them easily).
Now again this may seem obvious to make a point but I’ve seen teams fall into similar patterns, I think it’s often caused by thinking in terms of ‘feature’ and not ‘value’. The story is written to deliver the ‘feature’ in one go. Of course an entire feature could be a huge piece of work, much bigger than a sprint, so it needs to be split but instead of looking to do that on value the team can only see how to split it horizontally along component or solution lines.
The other danger with the feature mindset is that you are pushing your feedback until the end of the finished feature, horizontal slices will never give you end to end value until everything is finished. You have no validation of effort until the feature is finished and you find that effort entirely wasted.
A feature is made up of lots of individual pieces of value, a good product owner breaks down a feature into those component pieces and delivers each of them in turn adjusting the value of the next piece based on the feedback from the others. The beauty of this is that you can stop when you want, if a search box for titles does the 95% of the job then you might decide that the other two options can wait or will never be needed. Saving a lot of time effort and unneeded complexity.
What about Purely Technical stories?
This is an argument often raised by developers, there are stories which could be described as purely technical, infrastructure changes often fall under this remit. How then can these be expressed as a value based user story?
To give an example, on the software I work on there are a number of parts of the application that for various reasons are on Azure cloud services. Now these services are clunky to deploy, can be slow and really expensive. We’ve had a bit of an ongoing technical debt to convert these cloud services to functions, no functional changes just switching the infrastructure.
So surely this is a purely technical story? Well not entirely. There is a business reason for doing this piece of work, in this case cost and performance, so the story could easily be expressed in those terms.
Whatsmore by divorcing it from the explicit Cloud Service → Function, to something more focussed on the value ‘I want to save x amount and go this much faster’ has several benefits. Firstly it focuses you on the problem not the technology solution and it gives you a measurable outcome. It also means that if there was something that did the job better (a new thing released by Azure, another technology or platform) the criteria of the story could still be met without needing to change a word.
Wrapping it up
In conclusion User Stories are an important tool in the Agile tool chest and underpin good technical practice, good user stories support good code. However too often (in my experience) they’re an afterthought, poorly written, badly executed and little understood. I hope this article has given you some inspiration and some pointers to avoiding some of the obvious traps.
My ask of you is to do your own research, practice this as a skill and take it seriously. Do this and it will bring the reward of a clearer understanding of your domain and your code and a happier team.
