BYD TechThe short answer
A user story is a short description of one thing a user can do and why it matters to them, usually written as: as a type of user, I want to do something, so that I get a result. Add acceptance criteria, the plain checks that show the story is done. Keep each story small enough to build and test on its own, and write it about the user’s goal, not the screen or the code.
Key points
- Template: as a user type, I want an action, so that a result.
- Write about the goal, not the implementation.
- Acceptance criteria turn a story into something testable.
- Small stories ship. Big ones, called epics, get split.
- A story starts a conversation. It does not replace one.
The template
The common form comes from agile teams and is described in Atlassian’s and Mountain Goat Software’s guides: as a certain kind of user, I want to do something, so that I get a benefit. Each part does a job. The user says who. The action says what. The benefit says why, which is what lets the team suggest a better way.
| Weak story | Better story |
|---|---|
| Add a notifications system | As a clinic receptionist, I want to send appointment reminders in one click, so that fewer patients miss their slot |
| Build an export button | As an accountant, I want this month’s invoices as a spreadsheet, so that I can reconcile them in my own tools |
| Improve login | As a returning customer, I want to sign in with a link sent to my email, so that I do not need to remember a password |
Acceptance criteria
Acceptance criteria are the conditions that must be true for the story to count as done. They remove arguments at the end, because everyone agreed on them at the start. A common format is given, when, then.
- Given an appointment tomorrow, when the receptionist clicks Send reminder, then the patient receives a text message.
- Given a reminder was sent, then the appointment shows "Reminded" with the time.
- Given the message fails to send, then the appointment is flagged and the receptionist sees why.
What a good story looks like
- Independent: it can be built without waiting for another story.
- Valuable: a user or the business would notice it.
- Small: it can be finished and tested in a short cycle.
- Testable: the acceptance criteria can be checked.
- About the goal: it leaves room for the team to suggest how.
Splitting stories that are too big
A story that will take a long time, or that nobody can estimate, is probably several stories. Ways to split it:
- By step in a workflow: create, then edit, then delete.
- By user type: the customer’s view first, the admin’s later.
- By rule: the simple case first, the exceptions after.
- By data: one payment method first, others later.
- By manual first: do part of it by hand in the first version.
Where stories fit
Stories usually live inside a short requirements document that sets the problem, the goal and the scope. See How to write a PRD. Agile teams then build them in priority order, as described in Agile vs waterfall.
Scoping in our MVP development work ends with this in plain English: who it is for, the one job it must do, what waits, and a clickable flow to check it against.
Sources
Checked when this guide was written.
