Guide · Apps & software
Writing user stories and acceptance criteria
Most misunderstandings between businesses and developers come from requirements written as features ("add a filter") rather than needs ("a manager needs to find overdue orders for their clients"). User stories describe what a person needs to do and why; acceptance criteria describe how everyone will know it works. Together they give developers enough context to build the right thing and give you a way to check the result.
[ 01 ]
In short
In short
- 01
A user story says who needs something, what they need to do and why.
- 02
Acceptance criteria list the specific conditions that must be true for the story to be done.
- 03
Stories should be small enough to deliver and test in a short period.
- 04
Include edge cases and errors in the criteria — that is where most bugs hide.
- 05
Write stories together with developers; they will ask questions that improve them.
[ 02 ]
Guide
The format
"As a [role], I want to [action], so that [benefit]."
Examples:
- As a sales manager, I want to see all orders of my clients that are overdue for payment, so that I can call them before the end of the week.
- As a customer, I want to reorder my previous order in one click, so that regular purchases take less time.
- As a warehouse operator, I want to scan a product barcode to find its location, so that I do not search the shelves.
The "so that" part matters: it lets developers suggest better solutions and helps prioritise.
Acceptance criteria
Criteria describe the expected behaviour in concrete terms. A common format is Given / When / Then:
- Given a sales manager with three clients who have overdue invoices, when they open the "Overdue" view, then they see those invoices sorted by due date.
- Given an invoice paid today, when the manager refreshes the view, then it no longer appears.
- Given a manager without clients, when they open the view, then they see a message "No overdue invoices" instead of an empty table.
A simple checklist also works. What matters is that each criterion can be checked.
Include the unhappy paths
- What if data is missing or invalid?
- What if the user has no permission?
- What if an external system (payment, 1C) does not respond?
- What if two people edit the same record?
- What appears on an empty list?
These are often where real problems appear after launch.
Size
Stories should be small enough to complete and test quickly. If a story contains "and" several times, it can often be split. Large pieces of work ("customer portal") are epics that contain many stories.
Non-functional requirements
Some requirements apply across stories: speed, security, accessibility, languages, supported devices. Write them once as general criteria rather than repeating them in each story.
Stories vs specifications
User stories work well in iterative development, where details are refined together. For fixed-price projects or formal procurement, a more complete technical specification may be needed; stories can still form its core.
Using stories in the project
- Prioritise stories by value and dependency.
- Estimate them with the developers.
- Review delivered stories against their criteria. See software testing for clients.
- Keep the backlog current: new ideas become new stories rather than changes to stories in progress.
[ 03 ]
FAQ
Frequently asked questions
Who should write user stories?
The person who understands the business need — often a product owner or manager — together with developers who clarify details and feasibility.
How detailed should acceptance criteria be?
Detailed enough that two people would agree whether the story is done. If a criterion can be interpreted in several ways, make it more specific.
Do we need user stories for a simple website?
For a simple website, a page plan and design are often enough. Stories help most for applications with logic, roles and integrations.