19 Tips for Writing Better User Stories
In this guide to writing better user stories we cover 19 concepts you need to grasp when writing user stories. It is built from many years coaching teams on writing better user stories and provides techniques for dealing with common challenges faced by the hundreds of teams we’ve helped.
If you’re looking to improve your user story writing skills, we hope you’ll get a lot of value from this post.
Let's dive right in
1. A user story is a means to an end, not the end in itself.
What is a user story in Agile?
The first thing to remember when writing good user stories is that the user story is a means to an end. That is, the end goal is to create a shared understanding within the team and users of what you’re attempting to achieve and how you’re going to do it. The user story is a common vehicle for doing this.
A user story is a vehicle which helps Agile teams to gain a shared understanding of the user need for development and testing.
2. User Story Example
The user stories template below provides an example of the common pieces that make up a story.
Teams should adapt this template for user stories and add other interesting information the team needs to complete the story.
You can use a number of formats to articulate your requirements. There are no strict rules or standards for writing Agile User Stories, only guidance.
Certain patterns have emerged in the industry that help to solve common issues with articulating a common understanding of user needs.
3. Use a unique ID for requirements traceability
Jira ID: # – A unique ID for the story to provide a common reference point for requirements traceability throughout requirements, design, development, testing, release and Management Information.
In this example we’re using Jira as our Agile Lifecycle Management (ALM) tool.
4. Understand your workflow
Status – User stories follow some sort of workflow such as Analysis, Design, Development, Testing, UAT, Done.
This status field is set to indicate what step of the workflow the story is currently in.
5. User Stories form part of a hierarchy
Parent Epic – User stories are usually part of a requirements hierarchy such as Epic->Story or Epic->Feature->Story.
We find it helpful that all stories belong to a parent epic.
Most ALM tools provide great visualisation of the Epic->Story relationship allowing you to quickly orientate and navigate around requirements to build a powerful mental model of scope.
6. Every story should have a short descriptive title
Title – a short but very relatable summary of the story.
This is mentally more consumable than a lengthy “As a…I want..So that…” description, especially when you’re traversing the requirements hierarchy in other views or reports.
The title often starts with a verb.
7. "As a <user>, I want to <goal>, so that <benefit>" is a useful format but not compulsory!
As a…I want…so that… is a useful format to articulate a user need but it is not compulsory.
If you find yourself struggling to shoehorn your requirement into this format then perhaps you need to drop this format and opt for a better way to articulate the need.
We call these awkward stories. Indicators of an awkward story can usually be found in the first segment of the sentence. Here are some examples of awkward stories:
As a System…
As a Config…
As a Product Setup…
As a Developer…
As a Monitoring System…
A common anti-pattern is for tasks to be written as Stories as people are sometimes led to believe that all work should be articulated as a User Story.
If it’s a task, write a task. Don’t confuse tasks with sub-tasks.
8. Keep it simple but don't be afraid to add more detail is it helps
Additional information or narrative
Writing your story in the format “As a…I want..So that…” may not provide you with enough space to fully and clearly articulate the intent of the story.
Use this space to capture more narrative if needed.
Please avoid verbose, paragraph after paragraph of text that people are likely to glaze over whilst reading.
Less is often more. Keep it concise.
Don’t forget, user stories are not a replacement for good conversation and collaboration – you should treat them as a placeholder for a conversation.
9. Clearly define your acceptance criteria
Acceptance Criteria – this should be written BEFORE implementation. Think in terms of a predefined set of tests that must be met before the story can be marked as completed. This can include functional as well as nonfunctional requirements.
Given when then – this is a really useful format for capturing the intent of the story but as per the story description it’s not compulsory to write in this way.
If an alternative method is more practical and useful then use it – but ensure all parties agree with the alternative approach.
10. A user story is one of many ways to gain a shared understanding of a user need.
Enriching the written text of a story with diagrams, pictures, prototypes, simulations and other assets can really assist in establishing a common understanding of the intent of a story.
Common attachments include Wireframes, Screenshots, Test data, Data models, API references, technical diagrams, architecture diagrams, UML, sequence diagrams.
In addition to attachments you may also link out to other documents stored on Wiki’s, Sharepoint or other resources with a URI.
11. Apply INVEST principles when creating user stories
The INVVEST acronym (adapted from Bill Wake’s INVEST) is another useful set of principles for creating user stories. Each story should be:
Independent – The story can be delivered from concept to production independently of other user stories.
Negotiable – The story supports a healthy and constructive conversation and may evolve over time.
Valuable – Once completed, the story delivers value to the end user.
Vertically sliced – Stories should start and end at the UI incorporating intermediary layers and data layers, we call this vertical slicing.
Estimable – The story has enough detail to enable the team to relatively size it appropriately.
Small – The story is as small as possible.
Testable – The story clearly articulates the user needs in a way that allows it to be tested and how it will be tested.
Don’t forget, these are principles, not rules!
12. How to split user stories
Splitting user stories or breaking down epics is often challenging for teams. Batch-size plays such an important role in delivering software predictably. The smaller the batch-size the more frequently you can gain feedback. This in turn reduces risk.
Context plays a big part in correctly splitting stories but there are some common approaches. Common splits (adapted from and credit to Richard Lawrence) for splitting stories include:
split by workflow steps
If the story describes a workflow, split the story down into each step of the workflow.
Break the feature down to its minimum viable feature. Create additional stories to represent the incremental enhancement of the feature.
business rule variations
Each story represents an individual business rule.
cross cutting concerns
Split out stories that apply across all features such as validation or permissions.
simple / complex
Deliver the simplest functionality possible to meet the user need and then enhance it with additional stories for increased complexity.
variations in data
Start with one kind of data and then add other kinds of data as increments.
data entry methods
Start with a simple data entry method, then enhance with additional user stories.
Do the absolute basics first to get the story working and then enhance with additional stories to meet the performance requirements.
operations (e.g. CRUD)
Split your story by features orientated around Create, Read, Update, Delete functions. One story per operation.
breakout a spike
If there are too many unknowns preventing you from splitting the story, breakout a spike to find a way forward.
by acceptance criteria
The acceptance criteria can often provide a useful way to break the story down further if needed.
To learn more about splitting stories see our online training course.
13. What’s the correct level of detail for writing a good user story?
The correct level of detail to write in a user story will be guided by three major factors,
1) The proximity to the start of the sprint the story will be delivered in. If you’re writing stories for the next sprint then you would expect more detail than the level of detail required for a story which is 5 sprints away.
2) The level of detail required by the individual who will implement the story. Different people have different mindsets. Some are very data driven and analytical whilst others are more visual. This is why bringing the individuals who will actually implement the story closer to the point where the story is written is important. Story creation is a collaboration between multiple disciplines, not a BA writing stories on behalf of others. Stories evolve in the level of detail required over time. Detail can be added during development.
3) The complexity of the story. For example, if the requirement is simple or obvious then maybe a simple descriptive title on a card is enough. Complicated stories may need more detail such as using the story formats above but with more prescriptive supporting artefacts such as wireframes or data. For complex stories, don’t constrain the team but simply write the problem statement using one of the “As a…I want…so that…” format and let the team explore options and solutions with you.
For large projects or pieces of work, run an inception to de- risk and understand key areas such as Biz Case, Customer Journey, and Technical Architecture.
14. How far ahead of a sprint should we write stories?
The longer the period of time between a story being written and a development work starting degrades quality and requires a greater effort to start the work.
Ideally stories will be written just in time in collaboration with developers. If this is not possible in your circumstances then read on.
Known scope – the obvious stuff we know we need upfront.
For these items we can simply write out a list of stories keeping the level of detail high level.
Known Unknowns – the unknown scope we know we’ll need to discover.
Again for these areas of scope we can write out a list of epics that we expect will translate into a sub-set of stories once we do the discovery work.
Unknown Unknowns – the scope we didn’t know upfront for which we could have known upfront had we invested in discovering these unknown unknowns such as market testing or prototyping.
We tend to discover this scope as we iterate through the development of the product.
Unknowable Unknowns – the stuff that hits us from left field for which we could never have known upfront.
Structuring your Sprint board or Kanban board as per the illustration below can be helpful in understanding what level of detail is required at what point.
A simple title description at Epic level. Or a general dumping ground for work items we haven’t yet triaged or dealt with yet.
Epics broken down into stories. The only story detail is a short simple title and link to parent epic. You can schedule your stories into sprints at this point. This can be done weeks or months before sprint start but careful housekeeping is required to expire stories if not needed as the landscape may evolve
Add “As a…I want…so that…” if appropriate. Add acceptance criteria. Consider non-functional requirements. Consider data implications. Add supporting artefacts. This phase is ideally done as close to the sprint start as possible but no longer than 2 weeks before the sprint start.
Stories are Ready for Dev at this point.
The level of detail can still change during development. Stories maybe split or evolve at this point based on feedback.
15. Understand your Agile Requirements Hierarchy
In the diagram below we describe a common requirements hierarchy used by Agile teams.
- Epics can have Stories, Tasks or Defects as children.
- Stories and tasks can have sub-tasks and defects as children.
- Some teams use an additional tier called Feature that sits between Epic & Story.
Discipline plays a major role in Agile requirements management. Orphaned work items (defects / user stories / features) are commonplace in product backlogs. Ensure you do regular housekeeping on your backlog to keep it clean.
16. Who creates user stories in Agile?
Anyone can create a user story for an Agile team.
The Product Owner in Scrum is ultimately responsible for selecting which user stories are prioritised for development.
User story creation is a team sport.
User stories should be created by a cross functional team.
A common flaw in user story writing is when a Business Analyst or Product Owner writes a user story in isolation hands it off to the development team.
Never write stories without input from those who will implement the work.
They are critical in understanding the best way to break down a story or how to approach it.
User stories are created with developers, not for them.
17. User Stories are not Requirements in disguise
User stories vs requirements is a common question.
A User Story in Agile focuses on a specific user need. These needs are derived from conversations with real users to truly understand their needs. These needs are often tested with users to ensure they are a true reflection.
Requirements are often written with an assumption of the user needs, and rarely tested with users to validate these assumptions.
This is obviously a big difference with profound consequences in terms of outcomes.
18. How big should a user story be?
A user story should pass through dev and test within 3-5 days.
If you’re using a Scrum approach, then it certainly should be deliverable within a sprint.
If it’s too big, break it down using the story splitting strategies detailed above.
To learn more about sizing user stories, see our in-depth guide on how to size user stories properly.
19. Bonus Kanban Board Design
If you don’t use a sprint cadence then here is an example of how you might organise your stories across your Kanban board.
Note: the detail is added to the story “Just In Time” after the commitment point. The NEXT column is the commitment point in this example.
User story writing challenge
In reference to the table on the below “Functional Access & Permissions”, how many stories should you create and how would you slice them?
- 24? One story for each role for each functional permission, e.g. As a Booking Agent, I need access to Create orders, so that I can create orders on behalf of the Supplier.
- 3? One story for each role and articulate the access rules through Acceptance Criteria
- 1? One story called Functional Access & Permissions and attach the table of permissions
- You could actually have in excess of 72 test cases for this scenario!
How would you approach this – leave a comment below.
About Ian Carroll
Ian is a consultant, coach, trainer and speaker on all topics related to Lean, Kanban and Agile software development.
Connect with Ian at the following