Writing Clear User Stories | Sean Dinwiddie's Webmastery

Updated October 4, 2026· Development

Here is the test of a clear story: the owner and every webmaster on the job read it and picture the same thing. This lesson is how to write one that passes.

Start with the template

“As a [type of user], I want [an action] so that [benefit/value].” The classic template holds the user’s side and the value they expect in one sentence. Filling in all three parts is the first check on a story: a part left blank shows what the story doesn’t know yet.

Name a specific role

“As a user” could be anyone, which means it is no one. “As a customer,” “As an admin” or “As a first-time visitor” says who the story is about.

Keep it action-oriented

The “I want” or “I need” names something the user does, a verb you could watch someone do: call, book, reorder.

Be concise

One sentence, no jargon, nothing the user wouldn’t say themselves: the need and the value, and nothing else. The same care with names pays off in code; the lecture Basic Functional Programming TypeScript Knowledge makes the case for descriptive function names.

Include acceptance criteria

Acceptance criteria are the specific conditions that make the story done. They turn “I think it works” into a check anyone can run, and they guide the building and the testing.

Leave out the technical details

“Keep the number in a config file” is a note for the build, not a story. The story stays on the user’s need.

Run the INVEST check

Bill Wake’s INVEST criteria (2003) test the quality of a user story. INVEST stands for Independent, Negotiable, Valuable, Estimable, Small and Testable.

Independent: it stands on its own, with no other story built first.
Negotiable: it names the need, not the solution, so the owner and the webmaster settle the details in conversation.
Valuable: it delivers something the user wants.
Estimable: it is clear enough to size, so the written scope can price the job as a share of the published fee.
Small: it fits on one line in the written scope and finishes within one iteration.
Testable: each criterion can fail, and becomes a Given, When, Then scenario.

Leave priority to the scope

A story’s words carry no priority: “urgent” or “must” in the story tells a webmaster nothing about what to build first. The written scope carries it, listing each story as required or optional, in the order the owner chose.

Before and after

Before: “As a user, I want the site to be easier to use.” Nobody can build or test that. After:

“As a customer on my phone, I want to call the shop with one tap from any page, so that I can ask about an order without hunting for the number.”

User perspective: A customer on a phone
Action: Call the shop with one tap
Benefit/value: Ask about an order without hunting for the number

Its acceptance criteria

Every page shows the shop’s number as a link that starts a call.
The link’s text is the number itself, so a screen reader announces it.
On a screen 320 CSS pixels wide, the number shows without scrolling sideways.

The rule behind the examples. INVEST is a check to run on a draft, a letter at a time, and the tap-to-call story above passes it:

It is independent: no other story has to be built first.
It is negotiable: it names the need, a call in one tap, and leaves the form, a link in the header or a bar along the bottom of the screen, to the written scope.
It is valuable: a customer with a question about an order reaches the shop in one tap.
It is estimable, because a webmaster can say what it touches, the template every page shares, so the scope can price it.
It is small: one line in the scope.
It is testable, because each criterion can fail: a page without the link, a link whose text is an icon a screen reader can’t announce, a number that runs off a narrow screen.

The before version fails the last three letters: no one can size it, it has no end, and nothing in it can fail a test.

Independence is the letter real scopes bend most. In One feature, scope to launch, Story 2, seeing past orders, seems to wait on Story 1, placing one; a scenario that starts from “Given a customer with two past orders”, as Defining user stories writes it, lets the history be built and tested first. A dependency between two stories usually becomes a Given, not a reason to merge them.

INVEST as a checklist, a letter at a time. The before story fails the last three letters, in violet: no one can size it, it has no end, and nothing in it can fail a test. The tap-to-call story passes all six.

A clear story pays twice: the owner can read it in the written scope and say whether it is right, and a webmaster can build and test it without guessing.

The next lesson, Practical exercises in creating user stories, puts the template and INVEST to work in eight exercises, from finding a need to writing a criterion a test can fail.

Writing clear and concise user stories