Why good user stories matter:
The cost of detecting and fixing issues increases exponentially the longer they remain undetected in the workflow. Issues introduced at the beginning of a project are often, as a result, the most expensive issues to detect and fix.
1 Researchers at Hewlett-Packard, IBM, Hughes Aircraft, TRW, and other organizations have found that purging an error at the beginning of construction allows for rework to be done 10 to 100 times less expensively than when it's done in the latter parts of a project.
For many teams, the user story is the consolidation point of an idea into an achievable piece of functionality. This makes user story creation a key point in the development cycle as it can significantly influence the project’s success and cost down the line. As a result, by delivering high-quality stories, you will be capable of effectively minimizing the downstream likelihood (and cost) of issues giving your projects a better chance to succeed.
User story disclaimer:
Not everyone needs to use user stories or benefit from them. I’ve found user stories to be one of the lowest-effort ways to have documentation, alignment, and tracking for the development of a solution.
I’ve also tried many other ways, all having worked to different degrees of success/failure. It is not the system that makes your work succeed, it is how the team works together that truly matters. User stories are just another way to help teams work together more effectively.
That being said, many organizations find user stories to be the way they prefer to work so understanding how user stories can be made into effective collaboration, documentation, and tracking tools is a valuable skill for a PM to have.
User story principles:
I’ve found that to maximize the utility of user stories there are a few core principles to keep in mind:
User stories are owned by the entire team:
User stories represent agreements between stakeholders. They reflect the functionality the team has agreed to build along with the context behind that choice and its execution.
While there may be one main writer for the story, each team member can, and should, provide input on the story itself and feel ownership over it.
User stories should be written in such a way that anyone, even those who weren't involved in the writing/review process, can quickly understand them.
This ensures that anyone can easily pick up a story, regardless of their prior level of involvement on a project or how long it's been since the story was groomed. The following are the key items people should be able to quickly grasp when reading a user story:
The affected user
The functionality to be built
The intended outcome
The requirements to achieve that outcome
How you will validate that the implementation achieves the intended outcome
The effort required to tackle the story.
It takes teamwork to move stories through the workflow:
For a user story to be moved across the workflow there needs to be understanding and buy-in for the work to be done. Without team alignment, the story itself is worthless as it represents a truth that only a fraction of the team understands and believes.
Making this acceptance of a user story’s readiness into an explicit, workflow-based, action that the team performs together can help ensure each story is viable and maximized.
User stories represent an end-user outcome that can be enabled by executing the story:
Stories are expressed from the perspective of the end user (which in some cases may be a system) and explain a feature and its outcome.
Without an end-user value mindset, user stories can easily become ineffective and hard to grasp. Always ensure that the story actively describes an outcome to be achieved for the end user and the means to achieve it.
How to structure user stories:
I generally construct user stories using 4 key sections. These sections are:
User story
Additional context
Acceptance criteria
Testing plan
User story:
Template:
As a {{user type}} I want to be capable of {{action to be performed}} so that I can {{value to be experienced}}
Example:
As a paid user I want to be capable of favoriting a publication from the news feed so that I can track publications I’m interested in hearing more from.What it is: A description, from the standpoint of the user, of the outcome to be delivered and the means to achieve it.
Why it matters: This is the easiest, fastest way to create context for the entire team on the goal of the work item. By having this context anyone can understand and make effective decisions when executing on the story.
Questions for quality control:
Can someone who didn’t write the story understand its goal just by reading this section?
Does the whole team understand the user, the action, and the value? Do different people have different interpretations?
Is the user type clear and identifiable?
Is the story specific enough? Is the story too specific?
Is the end goal clear and is it easy to understand why it would be valuable?
Additional Context
Template:
There’s no template for additional context but generally this section is needed if there is supporting context that can be helpful to make a story likelier to be effectively tackled.
Things that fit this section:
• Links to relevant materials such as historical documentation on the feature the story touches.
• Explanations of the business context or motivation that lead to tackling the story.
• Related issues/stories that may be worth consulting. What it is: The supporting context for the user story.
Why it matters: Because sometimes user stories benefit from having additional context. This can help ensure that stories are fully understood.
Questions for quality control:
Is the team likely to understand the context of the story?
Is there a context for the story that if understood reduces risk?
Is there additional information about the underlying feature or system that would be important to understand when tackling the story?
Is there anything that could easily be missed that could lead to the story being incorrectly addressed?
Have we tackled something like this in the past? Should that previous work be consulted when tackling the story?
Acceptance Criteria (ACs)
Template:
There’s no template for ACs, different stories require different ACs. It’s up to the team to ensure these work for the story. A good starting point is:
Given {{the case in the story}}:
1. {{This is the state}}.
2. {{This action}} {{results in this outcome}}.
3. {{This action}} {{results in this outcome}}.
(…)
Example:
As a paid user on the feed, I should be capable of:
1.Seeing the favoriting button in the news card. The button should accurately reflect if the media publication is favorited/not favorited.
2. If the button was inactive (not favorited), clicking it should lead to the publication being favorited and the button should update to active.
3. If the button was enabled, clicking it should lead to the publication being unfavorited and the button should update to inactive.What it is: The high-level requirements that, if met, validate that the feature is working and delivering the user story outcome.
Why it matters: Because it creates a shared understanding of what requirements must be met for the story to be deemed complete. This makes it simple for anyone to determine if a story is complete or not.
Questions for quality control:
If this user story gives us trouble, what will be the reason?
Is the team capable of testing the ACs in order to validate that the feature works?
Did the team go through these ACs, review them, and agree they’re ready?
If someone wasn’t involved in the AC writing, would that person be capable of understanding them and testing the user story using them?
If just these ACs are met, does this story successfully pass testing? If not what’s missing?
Do we need a testing plan? Can we use the ACs to test it in this case or would we benefit from more info here?
Is there anything about testing these ACs that is messy/easy to miss?
Testing Plan
Template:
There’s no template for the testing plan, different stories require different testing plans or may not require them at all (if the ACs are clear and guiding enough). It’s up to the team to ensure these work for the story.
Example:
Checking that favoriting publications works
1.Login as a paid user
2. Go to the feed
3. Click the favorite button on the news card. This should flip the button to active.
4. Check the DB for a favorite record from the media publication for that user.
5. Click the favorite (unfavorite in this case) button for the same news card. This should flip the button back to inactive.
6. Check the DB for the same record. This record should now be soft deleted.
1. Login as a free user
2. Go to the feed
3. There should not be a favorite button on the news card. What it is: A series of steps the team can undergo to validate that the feature is working as intended.
Why it matters: For most tickets, the ACs are enough for the team to test. But for some tickets, you need more definition on how to test. This section allows the team to align on the testing plan when needed and document it for future use.
Questions for quality control:
Do we actually need a testing plan for this?
How do you successfully test this feature step by step?
Are there cross-user considerations?
Is testing of this dependent on something else?
Do we need a manual action (from a dev or someone else) to test this? Like running a command.
Can this be tested on our regular testing environments?
What user accounts do we need, and what data do we need? Do we have a means of generating that testing data?
How to scope user stories
The hardest part of defining a user story is determining its scope. While this is more art than science, there are questions you can ask yourself to help find the right scope:
Is the user story the right size?
User stories that are too large can slow down progress and hurt team morale as they make teams feel like the work is just not moving forward. Most times stories can be broken down into smaller stories which allow the team to more effectively, build, test, and release leading to faster value delivery.
It’s important to stress test stories for size and to keep in mind that most stories tend to be over-scoped. If you’re already breaking stories down, keep in mind that the reverse can happen as well. Sometimes teams can get overzealous with breakdowns leading to stories that don’t deliver value, feel incomplete, or are generally overvaluing size over value. Think about story size in terms of the end-user and the context of that story in the project, ask yourself “Can it be smaller” but also “Should it be larger”.
During the course of a project, it’s easy to bundle together items that don’t need to be bundled. It’s important to also ask yourself if there are pieces of the work that could be realistically done independently, or if there are parts that could hold back the story but shouldn't. This can help clarify story size and decouple the core parts of a story from the less essential parts.
Does the story make sense from the standpoint of the end user?
It’s easy to lose sight of the end-user when optimizing user stories and this can easily lead to stories that are perfectly shaped for moving through a workflow but deliver poor or incomplete value on delivery.
Ensure that the stories you’re writing deliver meaningful change to the end user be that end user an actual user or a system. Ask yourself if the story delivers actual value if achieved or if there is something missing.
Is the story testable?
If a story cannot be tested you cannot ensure that it’ll deliver on requirements and as a result you cannot ensure that it is completed. For a story to be effectively deemed complete it needs to be tested which implies you have a clear way to verify requirements.
If this is not possible, the team will need to determine why it’s not possible and problem-solve from there. In many cases, if a story is not testable it is because there are dependencies that need to be solved first which makes it so that the story needs to be tackled later on once those dependencies are met.
Don’t move stories into the workflow without knowing exactly how to verify that they were completed or you run the risk of realizing the story isn’t achievable in its current state and needs to be rethought.
Is the story in the right place in the sequence?
During projects, one of the main reasons why stories can fail is because they are being worked on in the wrong sequence which can make it so that the story is not testable or that if completed it does not meaningfully move the project forward.
If tackling stories within the context of a project it’s key to understand the order in which stories are to be tackled as this will ensure that each story can be effectively tested and completed. Ensure that the team has thought about how the sequential execution of stories will lead to a finished deliverable.
Is there a clear delineation between what is to be covered in the user story vs elsewhere?
At all times it should be clear what information is to be covered in user stories and what information is covered elsewhere. For example, it should be well understood by the team if user stories cover design specifications or if these are covered in design specks or other materials.
Ensure that everyone understands what information the user story is responsible for and what materials cover the remaining information needed to tackle the story. It is very easy to miss requirements as a result of having ambiguity in terms of what information lives where.
Parting thoughts:
It is important to remember that processes exist to ensure that certain things happen in the workflow. As a result, processes should be evaluated against their ability to ensure those things happen. It is also important to evaluate if those things happening are actually making the workflow better.
User stories exist, mostly, to help teams better define the work to be done, document it, and create alignment on it. If user stories are getting in the way of the team effectively collaborating and defining work then consider if 1. you and your team are using stories correctly or if 2. user stories are a fit for your team overall.
Ultimately, team workflows work best when they are iterative and allowed to evolve based on the needs and structure of the team but they also need time to improve and find the right shape. Don’t be afraid to question if the stories you’re writing are adding value and remember why you’re writing them in the first place.
Source: Code Complete: A Practical Handbook of Software Construction, Second Edition - by Steve McConnell which itself references: "Design and Code Inspections to Reduce Errors in Program Development" (Fagan 1976), Software Defect Removal (Dunn 1984), "Software Process Improvement at Hughes Aircraft" (Humphrey, Snyder, and Willis 1991), "Calculating the Return on Investment from More Effective Requirements Management" (Leffingwell 1997), "Hughes Aircraft's Widespread Deployment of a Continuously Improving Software Process" (Willis et al. 1998), "An Economic Release Decision Model: Insights into Software Project Management" (Grady 1999), "What We Have Learned About Fighting Defects" (Shull et al. 2002), Balancing Agility and Discipline: A Guide for the Perplexed (Boehm and Turner 2004).