User stories are fundamental artefacts in agile projects. They serve as the building blocks of a product or system, each capturing a need and a goal from the end user’s point of view. An end user is typically a user or stakeholder, but in more technical, backend-focused work, the user can be a system or a service instead.
The strength of a user story lies in its focus on what is important to the user or system. It reduces the risk of developing a product that does not address a genuine problem or business need, which is why a user story must contain a clear goal and explain why it matters.
Why do effective user stories matter?
User stories are usually small enough to be achieved in short intervals and represent parts of an overall product feature. Breaking big goals and ideas down into smaller elements helps the team to manage, visualise, and prioritise based on factors such as business value, user impact, criticality, and overall effort. If a user story is deemed as low priority, the team aren’t wasting time on curating documentation and designing solutions that aren’t needed.
User story structure: What to include
A good user story includes five key components:
Within the user story, you can also add technical details as supporting information, to help the team understand where the change needs to happen: a specific process, system, or part of the product.
The team should also ask the following questions:
- Is the goal time critical?
- Is there a deadline?
- Does it depend on third parties?
- Are there any dependencies?
Various agile tools allow teams to set dates and priority levels, dependencies between user stories, and details of whether user stories are successors or predecessors of others.
How to write acceptance criteria for user stories (including best practices)
Arguably, the most important element of any user story is the acceptance criteria. Acceptance criteria specify what needs to happen so that the goal can be verified and accepted as completed. Without it, the team cannot verify that the user story has been met or determine what needs to be tested. They also help manage expectations and keep the project on track.
There are many ways to write acceptance criteria. Some use bullet points, while others use acceptance criteria templates. At Koderly, we use the ‘Given… when… then’ template for its consistency and simplicity:
- Given that [precondition]
- When [action]
- Then [expected outcome]
Crafting well-defined acceptance criteria is an art. At Koderly, we make sure that the entire team contributes to the acceptance criteria. Essential elements of good acceptance criteria include:
- Clear, concise, and unambiguous: Everyone should understand the acceptance criteria. Reduce technical jargon and save it for technical documentation. A user story should be accessible to all stakeholders, even those that aren’t technical. If it cannot be clearly and concisely expressed, neither can the solution.
- Testability: If the solution does not meet the acceptance criteria, the user story cannot be considered complete.
- Specificity: Focus on one behaviour or outcome at a time. Can you test each criterion independently?
- Relevance: Do the acceptance criteria directly relate to the functionality and value described in the user story?
- Consistent format: Using a template such as ‘Given/then/when’ ensures that all criteria are well considered and not missed.
- Collaborative input: When everyone contributes, the output is a comprehensive acceptance criteria reflecting a shared understanding of the user story and goal.
- Measurability: The acceptance criteria are quantifiable and clearly state whether the requirement has been met.
How to improve user stories
User stories begin as ideas and discussion points from story mapping. Teams might find it useful to create user personas to explain who the user is, what they need, and why it matters. Remember that user stories are flexible and by the nature of agile can evolve as the project moves on.
Be prepared to revisit and adapt user stories to remain up to date with new user needs and stakeholder input. Most importantly, review old user stories and retrospect on what you could have done better, what you did well, and what you will change going forward. Successful agile projects are projects where teams reflect and continually improve.
Ever considered how you might write a user story for application security? Stay tuned for a blog on evil user stories.
