- Mark Shead: Creating Good User Stories
- GOV.UK Service manual: Writing user stories
- Mike Cohn's blog posts about user stories
- Mike Cohn: User Stories Applied (book)
- Splitting user stories (very important part):
User stories are a kind of software requirements, and software requirements are communication between those who want the software and those who will build the software:
People who want the software People who will build the software
---------------------------- ----------------------------------
- Customers - Developers
- Users
- Analysts <-- Requirements -->
- Domain experts
- Non-developers in the business
or organization
There needs to be a balance between the two sides of this communication. If the people who want the software dominate too much you end up with unrealistic requirements and deadlines, and developers don't understand exactly what's needed. Developers end up trading quality for features trying to meet the unrealistic deadline. Features end up partially implemented. Developers make decisions on their own that users should have been involved in.
The developers dominate they can end up not learning from users what the users need.
Use user stories as the center of your "home-grown story-drive agile process."
Some Agile principles that user stories support (from Mark Shead):
-
Working software is the primary measure of progress
-
#1 priority is satisfying user needs through early and continuous delivery of valuable software.
Based on a Ron Jeffries The Nature of Software Development I'd re-phrase this as delivering value, where value is defined as "whatever you want". Most of the time this should be user needs, but not always.
-
Keep it simple - maximize the amount of work not done
More paraphrasing from Mark Shead:
Software projects fail because they aren't focused on delivering actual value to the user regularly.
A software increment that completes a user story is a valuable software increment in terms of user needs. A delivered user story gives the user the ability to do something valuable with the software. So tracking work with user stories is a way to measure progress in terms of value (user needs) delivered. The same goes for prioritising work with user stories. User stories are units that represent value to the customer. Working from user stories and delivering frequently minimizes project risk.
From User Stories Applied: you can't predict a software development project. Users have new ideas or change their minds when they see early versions. Developers can't estimate accurately. Instead, make decisions throughout the duration of the project instead of trying to make them all up front. Use user stories as a way to get information early and often, and to support iterative development. Write user stories at any time throughout the project.
Opinions differ. Some say it's best if the customers write them themselves (e.g. User Stories Applied). GOV.UK have every member of the team involved in writing user stories, which I think is a good idea because it gets everyone thinking from the user's point of view and gets everyone to understand what makes a good or a bad user story, gets the team communicating with each other in terms of user stories.
I think it might be good if the product owner (or other non-dev people in the organization) write epics, and then developers split those into smaller stories.
One it comes to splitting up stories into smallers ones, and certainly splitting small stories into dev tasks, developers need to take the lead because it involves a lot of developer knowledge and concerns.
The customer, customer proxy or product owner should be the one who leads prioritizing the user stories, although dev input will be needed here on what sequence orders are possible or not and how / whether they affect cost. (And whoever wrote the stories should have tried to make them as independent from each other as possible so they can be prioritized as freely as possible.
You should do as much as you can to increase the quality of your user stories. This will pay dividends by making subsequent development more efficient. The user stories are the foundation on which a lot of time is going to be spent planning and developing, so get them right.
-
Who the user is (As a...)
-
What the user needs (I need/want/expect to...).
This (the goal) is the most important part because it's how you know that the thing you're building solves the right problem, and how you decide when a story is done (possibly with help from acceptance criteria).
-
Why they need it (So that...). Some people consider this part optional.
-
Optional acceptance criteria (It's done when...), a checklist of outcomes that can be used to confirm when a story is done.
You can also link to any supporting evidence in acceptance criteria.
2, 3 and 4 together must describe what the world must look like in order to mark this user story as complete.
Good examples:
-
As a UK resident, I want to get my details on the electoral register so that I can vote.
Acceptance criteria:
- It's done when the user knows how to register online
- It's done when the user knows how to download a form to register by post
- It's done when the user knows where to send the form
(Example from GOV.UK.)
-
As a registered user I want to change my password so that I can keep my account secure. (From Mark Shead.)
-
As a website visitor I want to subscribe to the mailing list for a product so I can get product updates through email. (From Mark Shead.)
This seems wrong to me. Surely As a website visitor I want to get product updates through email so that... (what is the point of these product updates?)
-
As an admin user I want to disable a user so I can prevent unauthorized logins by past employees. (From Mark Shead.)
Same problem as above.
-
As a mobile app user I want to save all my data to the cloud so I can access it from another device. (From Mark Shead.)
Same problem as above.
-
A few from Wikipedia:
-
As the HR manager, I want to create a screening quiz so that I can understand whether I want to send possible recruits to the functional manager.
-
As a manager, I want to browse my existing quizzes so I can recall what I have in place and figure out if I can just reuse or update an existing quiz for the position I need now
-
As a user, I can indicate folders not to backup so that my backup drive isn't filled up with things I don't need saved. (From Wikipedia)
-
INVEST:
-
Independent.
As much as possible stories should be independent from eachother, meaning that they could be developed in any order (or any subset of can be left out for good).
Dependencies between stories complicate prioritization and planning, get in the way of divvying up work between different developers.
Especially problematic if a high priority story depends on a low priority one, or a low cost story depends on a high cost one.
Dependencies can also complicate estimation in cases where the order that stories are implemented in affects how long each will take (it'll be much quicker to do X after Y is done).
-
Negotiable. A user story is a promise for a conversation. It should have just enough detail, and detail should be added as late as possible.
-
Valubable
-
Estimatable
If it's small (see below) then I'm not sure that it needs to be estimatable. Make stories small enough to do inside of one sprint. If the story's in a state where we're confident it's small enough then that should be good enough. No need to also put a silly estimate on it.
-
Small
-
Testable: clear acceptance criteria, so that developers can know when they're finished.
Card, conversation and confirmation: a user story (card) isn't a complete requirements or specification, it's a placeholder for conversations that will be had closer to the time of implementing ("a promise for a conversation").
These conversations among the dev team and between the dev team and the people who want the software and their proxies) should be ongoing throughout the project, not all up front.
GitHub issue comments, links to Slack discussions, etc work very well on GitHub issue user stories if you think of a user story as a placeholder for a conversation.
Defer adding detail to a card until when you have the best understanding, which is as close to implementation time as possible. Don't pretend you can know and write down everything in advance. Also don't spend time thinking about a feature until you're positive it's needed.
Before close to implementation time you can use the card as a place to list reminders of things to discuss or think about during implementation.
You can also add notes to a card earlier on and these notes can be used later to resume the conversation where it left off. To know how detailed the notes should be - it should be enough to resume the conversation later, even if the customer and user having the conversation are different people.
Adding too much detail to a card shuts down active thinking and discussion about the card when it comes time to work on it later. Makes it look like everything is set in stone.
Things that enable deferring detail on user stories until close to implementation time:
- Epics (split them up closer to the time), epic as placeholder for more detailed stories it'll be split into later
- Splitting them into smaller ones adds detail
- Adding acceptance criteria, notes, tests, links to further reading
- Add reminders of things to discuss later or things to consider when implementing
- Just the right amount of detail
- Detail just in time
- Keep the story itself, any notes, any tests, etc clearly separated into separate sections so that the notes don't clutter the actual story
For things that've already been decided you can add "Test..." notes to the card. E.g. "Test with VISA, MasterCard and American Express (it has already been decided that VIA MasterCard and American Express will be supported).
Test notes can also work as reminders of things to consider: "Test with expired cards".
Reading:
As a vice president of marketing, I want to select a holiday season to be used when reviewing the performance of past advertising campaigns so that I can identify profitable ones.
Acceptance criteria:
- Make sure it works with major retail holidays: Christmas, Easter, President’s Day, Mother’s Day, Father’s Day, Labor Day, New Year’s Day.
- Support holidays that span two calendar years (none span three).
- Holiday seasons can be set from one holiday to the next (such as Thanksgiving to Christmas).
- Holiday seasons can be set to be a number of days prior to the holiday.
-- Mike Cohn
As a user, I am required to enter a strong password when creating my account.
Acceptance criteria:
- Must have at least 8 characters
- Must contain at least 1 digit
- Must contain at least 1 uppercase letter
- Must contain at least 1 lowercase letter
- Must contain at least 1 symbol
-- Mike Cohn
Acceptance criteria add detail to a user story.
Acceptance criteria shouldn't make a story too big for one sprint (in that case split it into multiple stories).
Acceptance criteria should be of equal priority, if they aren't then split into separate stories so they can be prioritized separately.
I think developers need to split up user stories, because it requires developer knowledge and involves developer concerns.
The product owner won't be able to split up user stories on her own in a way that's useful for developers. Product owner doesn't know how much work each user story she creates implies so she can't make them equal sized. Product owner can't know about dependencies between user stories.
Different stories might have different priorities, is another reason for splitting them up. Most of the value for a story usually comes from a small part of the functionality - splitting might even let you deprioritize or throw away one of the new stories.
An epic:
As a user, I can backup my entire hard drive.
Some of the smaller stories this would split into:
- As a power user, I can specify files or folders to backup based on file size, date created and date modified.
- As a user, I can indicate folders not to backup so that my backup drive isn't filled up with things I don't need saved.
- ...
(Example from Mike Cohn)
Another example from Mike Cohn:
As a user, I can log in through a social media account.
Splits into:
- As a user, I can log in through my Facebook account.
- As a user, I can log in through my LinkedIn account.
- As a user, I can log in through my Twitter account.
What paths can the user take in performing the story? For example showing overnight, two-day, or slow delivery. Split into story 1: slow delivery (no choice) (and then presumably add two-day then add overnight).
Extract a "Spike to investigate..." card out of the user story card. Reduce risk and uncertainty, learn more about unfamiliar technologies. And discover new ways to better split the story.
Don't split a spike out of every story though. Use them when there's too much uncertainty about a story.
"Spike" label on GitHub issues.
Agile For All gives nine patterns:
-
Workflow steps
Build the simple end-end case, or the most common case, first and then the moddle steps and special cases.
As a content manager, I can publish a news story to the corporate website.
…I can publish a news story directly to the corporate website. …I can publish a news story with editor review. …I can publish a news story with legal review. …I can view a news story on a staging site. …I can publish a news story from the staging site to production.
-
Business rule variations
As a user, I can search for flights with flexible dates.
…as “n days between x and y.” …as “a weekend in December.” …as “± n days of x and y.”
-
Major effort
As a user, I can pay for my flight with VISA, MasterCard, Diners Club, or American Express.
…I can pay with one credit card type (of VISA, MC, DC, AMEX). …I can pay with all four credit card types (VISA, MC, DC, AMEX) (given one card type already implemented).
Most of the effort will go into implementing the first story.
The second new story depends on the first, but at least the dependency is clear.
Also, writing the user stories in this style defers the decision about what order the four credit card types will be implemented in (including which first), allowing those to be reprioritized freely.
-
Simple / complex
Capture the simplest version of something as its own story. Use acceptance criteria to keep it simple. Then break each variation and complexity into its own story.
As a user, I can search for flights between two destinations.
…specifying a max number of stops. …including nearby airports. …using flexible dates. …etc.
-
Variations in data / details
Separate stories for separate variations in data.
As a user, I can search for transportation providers by trip origin and destination.
As a user, I can search for transportation providers by trip origin and destination as counties.
As a user, I can search for transportation providers by trip origin and destination as counties, cities, towns, or neighborhoods.
Providers can serve different geographic areas for trip origin and destination.
As a content manager, I can create news stories.
…in English. …in Japanese. …in Arabic. …etc.
Another example from Lasse Koskela:
As a user looking for camera accessories I want to search for products so that I can avoid browsing through the whole product catalog.
Splits into subsets of that fully featured search functionality:
-
As a user looking for camera accessories I want to search for products by their name and description so that I can avoid browsing through the whole product catalog.
-
As a user looking for camera accessories I want to search for products by their price and availability so that I can avoid browsing through items I wouldn’t buy anyway.
If the difference between supporting 2 or 4 data fields is negligible then splitting this way doesn't make any sense.
-
-
Data entry methods, a.k.a. splitting by quality or by utility vs usability.
When complexity is in the UI not the functionality itself.
Separate stories to build the simplest possible UI and then to build better UIs. (The second story will depend on the first.)
As a user, I can search for flights between two destinations.
…using simple date input. …with a fancy calendar UI.
Example from Lasse Koskela:
As a beginning photographer I want to get recommended a camera kit to buy so that I don’t need to spend hours reading reviews to figure out which camera would suit me well.
Splits into:
As a beginning photographer I want to see a numeric sales rank so that I can better decide which camera to buy by comparing the sales of my alternatives.
As a beginning photographer I want to see a numeric sales rank grouped by buyer expertise level so that I can better decide which camera to buy by comparing the sales of my alternatives.
...
These are things that deliver value (helping the user make the buying decision), just not as much value as the original feature request for a clear recommendation.
-
Defer performance
When a large part of the effort is making it fast. But you can still learn from the slow version, and it still has some value to the user who can now undertake the action albeit slowly.
As a user, I can search for flights between two destinations.
…(slow—just get it done, show a “searching” animation). …(in under 5 seconds).
-
CRUD operations
The word "manage" always contains multiple actions:
As a user, I can manage my account.
…I can sign up for an account. …I can edit my account settings. …I can cancel my account.
Another example from Lasse Koskela:
As a shop keeper I want to manage the products being sold in my online store so that I can sell what people want to buy.
Splits into:
As a shop keeper I want to add and remove products from my online store so that I can sell what people want to buy. (Editing can be done by deleting and re-adding.)
As a shop keeper I want to edit product details in my online store so that I can avoid recreating a product to fix a typo etc. (If the first user story isn't done yet then adding new products must be done with raw SQL.)
-
Break out a time-boxed spike
If the story is too large and poorly understood do a spike to resolve uncertainty. After the spike either do the story or break the story up.
-
Splitting by role
Additional way of splitting from Lasse Koskela:
The initial user story involves two distinct users. Split into stories for each user:
Error handling. user friendly error messages detailed stack trace in log file unique error code displayed to user and in log file
Splits into:
As a user I want to see an error message I can understand when something goes wrong.
As a programmer I want to see the full stack trace in the log file for any exception thrown during runtime so that I can better debug error situations.
As a programmer I want to show the user a unique error situation identifier so that I can locate the relevant portion of the log file faster and more reliably.
-
Split user stories that are bullet lists into separate stories for each bullet! Or split where "and", "or", periods or other separators appear in the story.
Another example of splitting stories from J.B. Rainsberger:
"Collect registrations" splits into:
- register with just e-mail, then pay with paypal.com
- collect more information from registrant (name, address, phone)
- notify both registrant and organizer after registration
-
Unbalanced. 99% of the work is in one story.
-
Splitting along technical boundaries (backend, frontend, etc). Results in stories that give no user value. A story should go through the entire stack, or as much as the feature needs.
You can split along technical lines only if you can't think of any other way. Example:
As a potential buyer I want to see available multi-item discounts involving the product I’m currently looking at.
Splits into:
As a product owner I want the discount subsystem to support multi-item campaigns so that I can deliver value to the user in a later iteration.
...
(Example from Lasse Koskela.)
-
As a developer I want a database with all the tables to model the data so I store the information the application needs.
It's a prerequisite for other user stories. This is bad. Almost all of the application depends on this story being done first.
It depends on other user stories. This is bad. We can't know how to implement this user story (how to design all the database tables) until we know how we're going to build all the other parts of the system (that the database tables will serve).
Doesn't deliver user value. We have no functionality we can show the user when we've completed this story. The story isn't written from the user's perspective.
Instead you should write a small user story from the user's perspective and build only the parts of the database that you need (and only the parts of every other layer that you need) to complete that small user story. A thin, but top to bottom, slice.
This does means that code written for earlier user stories may need to be rewritten when we get on to later user stories and realise things that we didn't realise earlier. That's fine - the cost is trivial compared to the benefits of delivering customer / user value sooner rather than later.
-
Circular
-
Describing a solution not a problem.
-
Jumping right into how:
As a participant who has just finished a course, I'd like a more prominent call to action asking me for a review.
Instead start with the goal (to get more reviews). This user story has already decided that a more prominent call to action is how to get more reviews.
Just adding a "so that" (and leaving the prominent call to action in) is already an improvement:
As a participant who has just finished a course, I'd like a more prominent call to action asking me for a review, so that there are more reviews on the site.
But this still isn't right though (it's not the participant who wants more reviews, it's the course owner).
(Example from Mike Cohn.)
-
Wrong user.
As Front Row Agile, I want participants to be encouraged to review a course after finishing the course, so we can have more feedback about how folks like our courses.
-
Too much detail. Not everything needs to be known before starting a story.
Too much time spent on writing user stories. Takes longer to get feedback from users and stakeholders as time is spent adding detail to stories before actually delivering working code.
Loss of creativity, programmers are just doing exactly what they're told.
Details that are added too long before the details will likely not be right anymore by the time the user story gets worked on.
Implementation details start to creep in to the stories.
-
Too little detail.
Story is too hard to implement as time is spent seeking answers to unanswered questions, and/or development goes astray by filling in the gaps with the wrong things.
-
User stories that are prerequisites for and / or depend on other user stories.
-
Too big to implement directly (it's an epic, it needs to be split up). Needs to be small enough to deliver in a single sprint.
-
Specifying the solution as part of the user story.
User stories should focus on what needs to be done, not how it'll be done.
-
User stories as mini specification documents, and doing iterative waterfall instead of agile.
I've noticed something disturbing over the past two years. And it's occurred uniformly with teams I've worked with all across the world. It's the tendency to create an iterative waterfall process and then to call it agile.
Doing lots of Analysis -> Design -> Coding -> Testing mini waterfalls (one per user story) isn't agile, it's iterative waterfall.
In agile analysis, design, coding and testing start and finish at the same time. They overlap as much as possible, and upfront analysis, design etc are done as late as possible.
Don't treat user stories as mini specification documents.
Treat a user story as a promise to have a conversation.
Optionally, add notes to some user stories about things to make sure to bring up during that conversation.
-
Not everything needs to be a user story.
More technical, less user-facing tasks (APIs, system capabilities, ...) can instead be writting using Feature Driven Development (FDD) features in the format:
<action (verb)> the <result> <by|for|of|to> <object>Examples:
- Estimate the closing price of stock
- Generate a unique identifier for a transaction
- Change the text displayed on a kiosk
- Merge the data for duplicate transactions
-
Having a complicated story hierarchy or taxonomy (feature -> saga -> epic -> novel -> story -> headline)
Themes (groups of user stories), epics (big user stories that need to be split up), user stories and tasks will do.
https://www.mountaingoatsoftware.com/blog/adding-decorated-user-roles-to-your-user-stories
Don't just say "As a user" all the time, refer to specific types and sub-types of users:
- Site visitor
- Former member (more specific type of site visitor)
- Registered member
- Known visitor
- Unknown visitor
- Premium member
- Trial member
- First-time visitor (add an adjective)
- First-time member
- Forgetful member
The first 7 are first class users, significant to the success of the system and will appear often in user stories.
The others are decorated user roles. Maybe important but not really an entirely separate type of user.
You don't need a complex hierarchy or taxonomy of different types of story, just a few. A theme contains many epics and stories. A given sprint or sequence of sprints should have a single theme as its focus or top priority. An epic is a big user story that gets split into multiple stories at some point. Stories, once they're split up small enough, are the things you actually take into sprints. A story needs to be broken down into multiple within-sprint tasks (e.g. write the backend, write the frontend) in order to do it:
Theme -(many)-> Epic -(many)-> Story -(many)-> Task
This isn't a strict hierarchy, though, they're more like labels: you could have an epic that stands on its own, doesn't belong to a theme. You could have a story that doesn't come from an epic. You could have a task that isn't part of a wider story (e.g. tasks like "reboot the server"). So GitHub labels should work well for these.
Spike is another example of a potential GitHub label. A spike is a type of story.
A theme is a collection of user stories and epics.
An epic is just a big user story. Too big to implement directly. They tend to come before the smaller user stories (it's easier to write the epics first). Can end up being split up into dozens or hundreds of user stories.
Different types of epics:
- Compound stories: can be split into smaller stories.
- Complex stories: too much uncertainty. Split out a spike story.
Code this, design that, create test data for such-and-such, automate that, have a design review meeting.
Usually things done by one person.
Restricted to a single type of work (programming, testing, UI design, analysis, ...).
What developers break user stories down into. Task list on GitHub issue. "Task" GitHub label for standalone tasks.
- When there's too much uncertainty about a card, split a spike out of it
- Don't put the spike and the subsequent implementation story in the same sprint, too much uncertainty.