A Primer on User Stories

Nick Jenkins
Feb 16, 2017 · 5 min read
Image for post
Image for post

The Problem with Specifications

The traditional way of building software is to write down everything that the customer wants in a document called a specification or requirements document.

User Stories & Acceptance Criteria

A user story or feature describes functionality that delivers value to a user or a customer. It tells a story about how someone uses the product and what they will achieve with it.


The easiest way to learn to write user stories and acceptance criteria is by using “patterns”. By using these patterns repeatedly you form a common language within your team that you use to describe your requirements; which reduces ambiguity.

Users stories or Features

As a [type of user] I want [a feature]

Acceptance Criteria or Scenarios

Given [a known state] When [I perform an action]

Rules of Thumb

  • Each user story should have about 3–5 acceptance criteria
  • Each story should be independent and stateless — it should not rely on another story. If it does, you should consider splitting the story into sub-stories.
  • Avoid implementation details and focus on outcomes — don’t say how a thing is to be done, but what the outcome should be.
  • If you can’t write any acceptance criteria for your story then it’s likely that it can’t be implemented!

Standardising Your Language

In order to make the best use of user stories and acceptance criteria you need to standardise your language. If you refer to a “user” in one acceptance criteria and an “end-user” in another then it won’t be clear whether you are referring to the same thing.


  • And — you can extend each simple clause of an acceptance criteria by using “and” to specify another clause. For example when I fill the kettle with water AND plug it into the electricity AND turn it on
  • Background — if you have a number of acceptance criteria which have common clauses you can use a “background” statement to make them easier to read. Typically the background statement contains the common “given” and “when” statements for all clauses, but the “then” (outcomes) will be unique.

Executable Specifications

The pattern for criteria is from a language called “Gherkin”.

Image for post
Image for post

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch

Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore

Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store