How to Write User Stories (With Before-and-After Examples)

To write user stories a developer can build from, describe one specific user, one action and the reason behind it, then add a few acceptance criteria that define when the story is done. The classic format is "As a [role], I want to [action], so that [benefit]", and the "so that" part does more work than most people expect. Below you'll find six steps, five before-and-after rewrites and a checklist.

I'm a freelance developer based in Denmark, so I'm usually on the receiving end: the person who has to build, and quote, whatever the stories describe.

The short answer: five parts every story needs

Get those five parts right and you're most of the way there. The rest of this guide makes each part precise enough to build and price. Stories often come out of discovery, the first phase of a project, and my overview of how a software project runs from idea to launch shows where they fit.

Why a feature list isn't enough

Many specs start as a list: login, dashboard, reports, export. A list tells a developer what should exist, but not who uses it or what they're trying to get done. Two developers can read "reports" and build two completely different things, and both can fairly say they delivered what was asked.

A user story moves the focus from the software to the person using it, and that changes the questions a developer asks. Instead of "which columns does the report need?", the question becomes "what does the sales manager decide based on it?". The answer often leads to something simpler than you had in mind.

Ron Jeffries, one of the people behind Extreme Programming, described this back in 2001 as the three C's: card, conversation and confirmation. The card is a short reminder, the conversation is where the details get worked out, and the confirmation comes from tests that prove the work is done. That still holds: a story is an invitation to talk, not a contract.

User stories aren't a Scrum requirement either. The Scrum Guide doesn't mention them at all. They work just as well on a project with a fixed plan and a fixed price, and I've compared the two ways of running a project in agile vs waterfall.

They also suit cross-border work. If your developer is in another country, you can't walk over and clarify what you meant. A short story with sharp criteria travels far better than a long paragraph, especially when neither of you writes English as a first language.

How to write user stories in six steps

These steps take you from a loose idea to a story a developer can ask precise questions about.

1. List your users before you write a single story

Write down every role that will touch the system. There are usually more than you think: the customer, the employee who handles the case, the manager who needs an overview, and the admin who creates accounts and fixes mistakes.

Use the names your team actually uses, such as "warehouse picker" or "accounts payable clerk". Avoid "the user" as a catch-all. Each role has its own needs and often its own permissions, and that shapes how the system gets built.

2. Write the action as something a person does

The action should be a verb: find, approve, order, cancel, send. Describe what the person does, not what the system has. "As a finance manager, I want an invoices page" says nothing about the job. "As a finance manager, I want to approve supplier invoices" does.

Stick to one action per story. If you catch yourself writing "and", split it.

3. Always write the "so that"

The benefit is the part people skip most often, and the part that helps a developer most. It tells them what matters, and therefore what can be simplified. Does the customer need to see invoices to pay them, to forward them to their accountant, or to settle a dispute? Three answers, three different features.

If you can't write a benefit, ask whether the story belongs in the project at all. It's one of the cheapest ways to cut a budget.

4. Add acceptance criteria

Acceptance criteria are the conditions that must be true before a story counts as done. They make sure you and the developer agree on what "done" means. Three to six is enough for most stories. If you need more, the story is probably too big.

Spend most of your effort on the exceptions. What happens when a search returns nothing, a payment fails, or two people edit the same record at once? That's where project time goes, and where misunderstandings start.

Some teams write criteria as Given, When, Then: "Given a customer has an active booking, when they cancel more than 24 hours ahead, then they get a full refund." The format is called Gherkin and is used by testing tools such as Cucumber. You don't have to use it, but it forces you to think through situation, action and outcome.

Good criteria can later become automated tests that check the rules after every change, which is one reason automated testing saves money even on small projects.

5. Split stories that are too big

A story that covers a whole area, like "As a customer, I want to manage my account", is often called an epic. It works as a heading, but it's too big to price. Bill Wake's INVEST checklist from 2003 says, among other things, that a good story is small and testable.

Split along the user's workflow, not the tech stack. "Build the database" and "design the screen" are the developer's tasks, and you can't prioritize or test them. Useful ways to split:

• by workflow step: create, edit, delete
• by business rule: standard pricing first, discounts as a separate story
• by happy path and exceptions: the payment that goes through, and the one that fails

6. Give every story a priority

Tag each story as must have, should have or later. Be strict with "must have". Ask whether the system can do its most important job without the story. If it can, the story doesn't belong in that pile.

How good stories get you a more accurate quote

A developer pricing your project has to guess at everything that isn't written down, and every guess turns into contingency in the quote. With clear stories, they can estimate each one separately, ask about the vague ones and flag the stories that cost a lot compared to what they deliver.

Acceptance criteria usually move the price more than anything else in a story. "Customers can cancel a booking" looks small. "Customers can cancel, get refunded according to the policy, staff are notified and the slot opens up again" is bigger. But now the real size gets priced up front instead of discovered halfway through.

Priorities do the rest. Once each story has a price, you can see exactly what version one costs and push stories to "later" until it fits your budget. This is also what makes a fixed price realistic: if you can describe what done looks like and how you'll test it, a developer can commit to a number. My comparison of fixed price vs hourly billing covers when each one fits.

Two tips when you send stories out:

• Send the same version to everyone you ask for a quote. Otherwise you can't compare the answers.
• Expect questions. A developer who comes back with questions has read your stories. A quote with zero questions should make you a little suspicious.

Before and after: five weak stories, rewritten

These are the kinds of stories that show up in first drafts, with a rewrite for each. The examples are invented for this article, but the problems are common ones.

The vague one

Before: "As a user, I want a dashboard."

Which user, showing what, to decide what? The developer can only guess.

After: "As a warehouse manager, I want to see which products are below their reorder level, so that I can restock before they sell out."

• The list shows product, current stock and reorder level.
• Products with zero stock appear first.
• The list updates when an order ships.

The solution in disguise

Before: "As an admin, I want an Export to Excel button for invoices."

This describes a solution, not a need. It might be the right one, but it shuts the door on a better idea.

After: "As a bookkeeper, I want each month's invoices in our accounting software without retyping them, so that month-end close takes less time."

With the real goal on the table, a developer might suggest a direct integration with Xero or QuickBooks instead of a file someone moves by hand every month. Maybe the spreadsheet is still the cheapest answer. At least now it's a deliberate choice.

The everything story

Before: "As a customer, I want to sign up, log in, reset my password, update my details and delete my account."

That's five stories with very different rules. Deletion alone raises questions: under GDPR a customer can ask you to erase their personal data, but you usually still have to keep invoices for tax purposes. That's a decision, not a detail.

After: five separate stories, for example:

• "As a customer, I want to sign up with my email, so that I can track my orders."
• "As a customer, I want to reset my password by email, so that I can get back in if I forget it."
• "As a customer, I want to delete my account, so that you no longer hold my personal data."

Each one can now be prioritized on its own. Maybe support handles deletions manually in version one.

The technical one

Before: "As a developer, I want to set up the database."

That's a technical task, not a user story. None of your users need a database. They need what the database makes possible.

After: delete it. The database gets built as part of the stories that need it. Let the developer manage technical tasks, and keep your stories about what people need to do.

The happy-path-only one

Before: "As a customer, I want to cancel my booking."

Sounds complete, but the important questions are missing: when can they cancel, and what happens to the money?

After: "As a customer, I want to cancel my booking, so that I don't pay for a slot I can't use."

• Given a booking more than 24 hours away, when the customer cancels, then they get a full refund.
• Given a booking less than 24 hours away, when the customer cancels, then they see a no-refund warning before confirming.
• When a booking is canceled, then staff are notified and the slot opens for other customers.

What stories can't capture

User stories are good at describing what people need to do. They're weaker at everything else, and everything else often moves the price just as much.

• Performance, security and hosting requirements don't fit the format. Where data must be stored, and how bad an hour of downtime would be, belong in a separate section. My software requirements specification template has one for exactly that.
• Complex business rules, such as pricing with discounts, subscriptions and exceptions, are clearer as a table of examples than as twenty stories.
• Integrations need a list of the systems involved and, ideally, access to their API documentation.
• Layout and flow are easier to explain with a rough sketch than with three paragraphs.

Not everything needs to be a story. "Fix the phone number in the footer" is just a task. For a single new feature in a system you already have, a short description and a call is often enough.

Need help writing them? If you have a product owner who knows the business and has the time, they should usually write the first draft, with a developer reviewing it afterwards. If there are lots of open questions, a paid discovery phase where you write them together is often cheaper than collecting quotes built on guesswork.

Next steps: check your stories before you send them

Once your stories pass, they're ready to be priced. My pricing page explains how I put fixed prices and discovery phases together, and what happens before a project starts.

Frequently asked questions

Who should write user stories, the client or the developer?+

Whoever knows the users best should write the first draft, and that's usually you as the client. A developer is good at spotting gaps, splitting stories and asking about edge cases, but can't guess how your business works. The best results typically come from going through the stories together, for example in a discovery phase.

Can I write user stories in my own language?+

Yes, as long as everyone on the project reads it fluently. If your developer or part of the team doesn't, write them in plain English with short sentences. What matters most is that role names match the words your team uses every day.

What tool should I use to write user stories?+

A spreadsheet or a shared document is enough for most projects. Tools like Jira, Linear, Trello or GitHub Issues are useful once development starts and stories need tracking from idea to done, but they don't make the stories any better. Start simple, and move them into a tool when your developer suggests it.

Can I change user stories once development has started?+

Yes, and that's part of the point. A story is the starting point for a conversation, and learning things along the way is normal. On a fixed-price contract, though, changes need to be agreed and priced before they're built. New stories or updated acceptance criteria give you the clearest basis for that conversation.