A written user story is a very short narrative—a sentence or two—describing some small piece of functionality that has business value. User stories are intended to foster collaboration and communication, but writing these short narratives poorly can negate agile’s flexibility. If you create a mediocre story, you risk that the story will drift away from business value or the story will be difficult to decompose into smaller units of business value. Recognizing some common failure patterns will help you focus on the right role, value, and business functionality when writing stories, leading to a more flexible development effort.
User Story Format
It helps to look at written stories via a standard format. The format isn’t going to ensure success, but it is a proven way to write agile-ready requirements. The most widely used story format was introduced by agile pioneer Mike Cohn as a way to focus on the intended user and the story’s business value, and to encourage the story to be decomposed. The format is shown below:
As a < role >
I want to < do something >
So that < business value >
As an administrative user
I want to deactivate another user’s account
So that they can no longer log in or receive email notifications
For the purpose of this article, we’re going to focus on each part of the format from the table. We’ll use examples from Manny’s Food Service, a wholesale food delivery company. Manny’s is creating a system to process food lists through which restaurants can order or reorder food. These food lists can also be used as templates to create more lists. Either the restaurant owners or Manny’s customer support specialist (CSS) can use the system.
Excessive ‘So That’ (Misplaced Requirement)
The team typically expects details of a story to be found before the conjunction “so that,” which is used to explain the story’s value. When the product owner writes requirements in the “so that” section, it is easy to miss part of the real requirement since it’s hidden after “so that.” You can tell if there is a problem when the “so that” section is complex or has multiple parts. In this case, the true story may be so big that it can’t get done in a sprint.
Example: As a Manny’s food service customer I need to save my list so that later I can save a copy, print, or email the list for other uses.
Problem: A team presented with this story may think, “Save a list? Okay, sounds pretty simple.” But the value statement infers otherwise. If the ability to copy, print, and email a list is what the product owner really wants, it would be too big—a compound user story made up of many pieces. Because of the confusion, a programmer or tester is likely to miss that the product owner wanted printing and emailing, not just saving, to be done as part of the story.
Improvement: As a Manny’s food service customer, I need to save, copy, print, and email my list so that I can edit it again, check a received shipment against a printed list, and send the list to a restaurant.
The requirement is no longer misplaced, but the story is now too big and needs to be broken down into a copy, print, and email type of story.
Odyssey (Ultra-Huge Story)
If team members can’t even estimate a story at a gross level, they may take on too much work in the iteration and not get to done. An Odyssey is beyond an epic. It’s something compounded or diffused to the point of having no discernable value (which an epic has). Such a story will lead to long conversations with the product owner, or even a failure to get to done. The team’s velocity will be unpredictable, and team members might be frustrated with a constantly evolving story.
Example: As a Manny’s food service customer, I need to save, copy, print, and email my list so that I can edit it again, check a received shipment against a printed list, and send the list to a restaurant.
Problem: This example shows a very large story that is hard to estimate and hard to implement in a sprint. It’s difficult to see the value that holds this story (or epic) together. Stories containing “and” or “or” are likely candidates for splitting into several smaller stories.
Improvement: We need to split the large story into multiple stories:
As a Manny’s food service customer, I need to save my list so that I can reorder from the list to create more accurate food orders.
As a Manny’s food service customer, I need to copy my list so that I can use it as a starting point for creating another list.
As a Manny’s food service customer, I need to print my list so that I can check a received shipment against the printed list.
As a Manny’s food service customer, I need to email my list so that I can have someone who doesn’t use the system review my list.
Stories that contain only analysis, design, or technical aspects lead to waterfall development in two-week phases.
Example: As a developer, I want to finalize the database table changes and additions for the release so that we don’t have to make changes to the model later.
Problem: This story has no business value and a user (“developer”) who is not really a system end user. There is only the technical side of the equation. This story will likely lead to coding with a separate testing story.
Improvement: Remove this developer story because it’s not really a user story. Instead, evolve the database as part of other stories. Develop the software in thin, vertical slices rather than horizontal architectural layers. Always provide business value in every story.
Stories with too much detail are often inflexible, leaving little room for creativity, better solutions, or dynamic scope control during development. Avoid this by postponing decisions on details that constrain the solution or that specify an implementation. Defer these decisions to a later but still responsible moment in order to maintain maximum flexibility. The product owner is likely to get exactly what he asks for instead of what he really needs.
Example: As a Manny’s food service customer, I want to see different food item types displayed in different colors—RGB = #FF0000 for meats, #A52AFA for grains, and #808000 for vegetables and fruits—so that I can quickly identify my food items by food type.
Problem: There may be better solutions that leave more flexibility, like using general colors or using intent of the colors rather than the color themselves. Specifying this level of technical detail handcuffs the programmers and possibly limits innovation.
Improvement: As a Manny’s food service customer, I want my custom item code to stand out so that I can find it on the screen more quickly.
For Whom? (Non-User)
There are a lot of different types of non-user stories, like using a specific name, a role, or the system. It’s better to write user stories for the role that actually wants the benefit or value provided by the user story.
Example: As a the marketing manager, I would like logins to time out and log off after a preset number of seconds in case users leave their computers unattended.
Problem: A marketing manager may be a meaningless role if marketing uses the system exactly the same as advertising. Perhaps departments have administrators, super users, and casual users who use the system differently. In this case it may be better to have a role of administrator, super user, or casual user.
Improvement: As a customer who is logged in, I would like my login to time out and log off after a preset number of seconds so that I can leave my computer unattended and still have some measure of protection against unauthorized use.
At the other extreme is the most overused and overly vague persona: “As a user” and its variants. Knowing the specific role for a story helps us understand the context for the story, leading to better value and focus.
Example: As a business user, I would like a report of item profitability so that I can identify and highlight profitable items and consider what to do about underperforming items.
Problem: Who is this vague user? Is there a specific role that is interested in this report? Understanding that this story is for a specific role enables conversations about how to limit scope. In the previous example, “marketing manager” wasn’t appropriate; sometimes it is.
Improvement: As a marketing manager considering how to spend limited marketing dollars, I need a report of the most/least profitable items so that I can identify and highlight profitable items and consider what to do about underperforming items.
Another non-user is “the system.” Beginning the user story with the phrase “As the system” may enable teams to use a waterfall approach. The system doesn’t care if business value is delivered or not. With the waterfall approach, no business value is delivered until the end.
Example: As the system, I need to store customer account info and their order lists in the database.
Problem: This story doesn’t deliver any value to the end user. Manny’s users cannot directly use the database.
Improvement: These aren’t good stories by themselves. For most applications, avoid creating stories just for database work. Add the database capabilities as a task to other user stories. Good user stories are thin, vertical slices through the application and provide business value.
Beware when the story’s “so that” phrase is a restatement of the story’s “I want” phrase. This points to a lack of analysis depth. The real goal of the story is not at all clear, making it easy to be off target and develop software that doesn’t maximize business value. Such stories are often not analyzed well enough.
Example: As a customer ordering food, I want to locate previous food order lists so that I can see all the lists that I have.
Problem: This story doesn’t explain its value. In the case of Manny’s, why does the customer ordering food need to see lists? The answer could influence the usability.
Improvement: As a customer ordering food, I want to see my saved food order lists so that I can reuse the list for future orders, making ordering faster and more accurate.
Beware of user stories where “so that” is a technical capability, not any value to the end user. This is very similar to no business value, but the value listed is technical.
Example: As a tester, I want to have detailed test plans so that when the system is completed, I can test the system.
Problem: This story refers to a specific user and has a technical benefit: the existence of test plans. Users want quality software, but they don’t care about test plans
Improvement: The improvement would be to delete this story. Part of the team’s test plan should be found in the acceptance criteria for each story.
Recognizing the common failure patterns in these written stories will help you avoid these problems and keep your conversations from losing their focus, leading to a more flexible development effort. Writing better stories will influence the conversations that happen, so it’s well worth the time up front to understand the value and format of a good story.