A User Story Primer

DZone 's Guide to

A User Story Primer

· Agile Zone ·
Free Resource

In this three part article series, co-author Pete Behrens and I provide an overview on the derivation and application of user stories, which are the primary agile mechanism that carries customer’s requirements through the agile software development value stream. In turn, user stories are a critical element of the Lean and Scalable Requirements Information Model for Agile Enterprises and The Big Picture of Enterprise Agility, both of which may be found on my blog: http://scalingsoftwareagility.wordpress.com/.

This article is extracted from the forthcoming book Agile Requirements: Lean Requirements Practices for Teams, Programs and the Enterprise, scheduled for publication in 2010. A special thanks to Jennifer Fawcett and Don Widrig for their contributions as well. 

By Dean Leffingwell and Pete Behrens


In agile development, the user story is a lightweight and more nimble substitute for what has been our traditional means of specifying software requirements - software requirements specifications, use case specifications, and the like. Indeed, an argument can be made that the user story is the most important artifact in agile development, because it is the container that primarily carries the value stream to the user, and agile development is all about rapid value delivery.

The user story also serves as a metaphor for our entire, incremental-value-delivery approach, i.e.:

Define a valuable user value story – implement and test it in a short iteration - demonstrate/and or deliver it to the user – capture feedback – learn – repeat forever!

I’ve discussed user stories briefly in the context of my broader whitepapers, A Lean and Scalable Requirements Information Model for Agile Enterprises and The Big Picture of Enterprise Agility (1) , where , along with themes, epics, and features, they are primary requirement artifacts used by the agile teams.

In this article, we’ll describe the user story in more detail, because it is here we will find one of the key agile practices that help us to align our solution directly to the user’s specific needs, and help assure quality at the same time.


User Story Overview

In the referenced whitepapers and the related blog series, I’ve highlighted many of the contributions of the Scrum model to enterprise agile practices, noting for example, the definition of the product owner role, which is integral to our requirements practices. But it is to XP that we owe the invention of the user story, and it is the proponents of XP that have developed the breadth and depth of this artifact. However, this is less of a “methodological fork in the road” than it might appear, as user stories are now routinely taught within the constructs of Scrum training as a tool for building product backlogs and defining Sprint content. Perhaps we have Mike Cohn to thank for much of this integration, as he has developed user stories extensively in his book User Stories Applied [Cohn 2004], and he has been very active in the Scrum Alliance as well.

For our purposes, we’ll define a user story simply as:

A User Story is a brief statement of intent that describes something the system needs to do for the user.

In XP, user stories are often written by the customer, thus integrating the customer directly in the development process. In Scrum, the product owner often writes the user stories, with input from the customers, stakeholders, and the team. However, in actual practice, any team member with sufficient domain knowledge can write user stories, but it is up to the product owner to accept and prioritize these potential stories into the product backlog.

User stories are a tool for defining a system’s behavior in a way that is understandable to both the developers and users. User stories focus the work on the value defined by the user rather than a functional breakdown structure, which is the way work has traditionally been tasked. They provide a lightweight and effective approach to managing requirements for a system.

A user story captures a short statement of function on an index card, or perhaps with an online tool.


  • Log in to my web energy-monitoring portal
  • See my daily energy usage
  • Check my current electricity billing rate

Details of system behavior do not appear in the brief statement, and are left to be developed later through conversations and acceptance criteria between the team and the product owner.

User Stories Help Bridge the Developer – Customer Communication Gap

In agile development, it is the developer’s job to speak the language of the user, not the user’s job to speak the language of technology. Effective communication is the key, and we need a common language. The user story provides the common language to build understanding between the user and the technical team.

Bill Wake, one of the creators of XP, describes it this way (2):

A pidgin language is a simplified language, usually used for trade, that allows people who can't communicate in their native language to nonetheless work together. User stories act like this. We don't expect customers or users to view the system the same way that programmers do; stories act as a pidgin language where both sides can agree enough to work together effectively.

With user stories, we don’t have to understand each other’s language with the degree of proficiency necessary to craft a sonnet; we just need to understand each other enough to know when we have struck a proper bargain!


User Stories Are Not Requirements

While user stories do most of the work previously done by software requirements specifications, use cases, and the like, they are materially different in a number of subtle, yet critical ways.

  • They are not detailed requirements specifications (something a system shall do) but are rather negotiable expressions of intent (it needs to do something about like this)
  • They are short and easy to read, understandable to developers, stakeholders, and users
  • They represent small increments of valued functionality, that can be developed in a period of days to weeks
  • They are relatively easy to estimate, so effort to implement the functionality can be rapidly determined
  • They are not carried in large, unwieldy documents, but rather organized in lists that can be more easily arranged and re-arranged as new information is discovered
  • They are not detailed at the outset of the project, but are elaborated on a just-in-time basis – thereby avoiding too-early specificity, delays in development, requirements inventory, and an over-constrained statement of the solution
  • They need little or no maintenance and can be safely discarded after implementation (3)
  • User stories, and the code that is created quickly thereafter, serve as inputs to documentation, which is then developed incrementally as well


User Story Form

Card, Conversation and Confirmation

Ron Jeffries, another of the creators of XP, described what has become our favorite way to think about user stories. He used the alliteration, Card, Conversation, and Confirmation (4) to describe the three elements of a user story. Where:

Card represents 2-3 sentences used to describe the intent of the story. The card serves as a memorable token, which summarizes intent and represents a more detailed requirement, whose details remain to be determined.

Note: In XP and agile, stories are often written manually on physical index cards. More typically in the enterprise, the “card” element is captured as text and attachments in a spreadsheet or agile project management tooling, but teams often still use cards for early planning and brainstorming, as we will see later.


Conversation represents a discussion between the team, customer, product owner, and other stakeholders, which is necessary to determine the more detailed behavior required to implement the intent. In other words, the card also represents a “promise for a conversation” about the intent.

Confirmation represents the Acceptance Test, which is how the customer or product owner will confirm that the story has been implemented to their satisfaction. In other words, Confirmation represents the conditions of satisfaction that will be applied to determine whether or not the story fulfills the intent as well as the more detailed requirements.

With this simple alliteration, we have an object lesson in how quality in agile is achieved during, rather than after, actual code development. We do that by simply making sure that every new user story is a) discussed and refined in whatever detail is necessary, and b) is tested to the satisfaction of the key stakeholders.



User Story Voice

In the last few years, a new, standardized, form has been applied which strengthens the user story construct significantly. The form is as follows:

As a <role> I can <activity> so that <business value>


·       Role – represents who is performing the action or perhaps one who is receiving the value from the activity. It may even be another system, if that is what is initiating the activity.

·       Activity – represents the action to be performed by the system.

·       Business Value – represents the value to the business.

We call this the “user voice” form of user story expression and find it an exceedingly useful construct [1] because it spans the problem space (<business value> delivered) and the solution space (<activity> the user performs with the system). It also provides a user-first (<role>) perspective to the team, which keeps them focused on business value and solving real problems for real people.

This user story form greatly enhances the why and how understanding that developers need to implement a system that truly meets the needs of the users.

For example a user of a home energy management system might want to: [2]

As a Consumer, (<role>) I want to be able to see my daily energy usage (<what I do with the system>) so that I can start to understand how to lower my costs over time (<business value I receive>)”.

Each element provides important, expansionary, context. The role allows a segmentation of the product functionality and typically draws out other role-based needs and context for the activity. The activity typically represents the ‘requirement’ needed by the role. And the value communicates why the activity is needed, which can often lead the team to finding possible alternative activities that could provide the same value for less effort.

User Story Detail

The details for user stories are conveyed primarily through conversation between the product owner and the team, keeping the team involved from the outset. However, if more details are needed about the story, they can be provided in the form of an attachment (mockup, spreadsheet, algorithm, or whatever), which is attached to the user story. In that case, the user story serves as the “token” which also carries the more specific behavior to the team. The additional user story detail should be collected over time (just-in-time) through discussions and collaboration with the team and other stakeholders before and during development.

User Story Acceptance Criteria

In addition to the statement of the user story, additional notes, assumptions, and acceptance criteria can be kept with a user story. Many discussions about a story between the team and customers will likely take place before and during the time the story is committed to code. The alternate flows in the activity, acceptance boundaries, and other clarifications should be captured along with the story. Many of these can be turned into acceptance test cases, or other functional test cases, for the story.

For example,

As a Consumer, I want to be able to see my daily energy usage so that I can start to understand how to lower my costs over time

Acceptance Criteria:

·       Read DecaWatt meter data every 10 seconds and display on portal in 15 minute increments and display on in-home display every read

·       Read KiloWatt meters for new data as available and display on the portal every hour and on the in-home display after every read

·       No multi-day trending for now (another story).

·       Etc…

Acceptance Criteria are not functional or unit tests, rather they are the conditions of satisfaction being placed on the system. Functional and unit tests go much deeper in testing all functional flows, exception flows, boundary conditions, and related functionality associated with the story.

Part 2 of this series will explore how agile teams can invest in better user stories by leveraging Bill Wake's INVEST model which provides an effective framework for measuring specific user story attributes.  


(1) www.scalingsoftwareagility.wordpress.com

(2) http://xp123.com/xplor/xp0308/index.shtml

(3) Subject to the development and persistence of acceptance tests, which define the behavior of the system in regression-testable detail

(4) http://xprogramming.com/xpmag/expcardconversationconfirmation/

(5) While looking for the origin of this form, Leffingwell received the following note from Mike Cohn: “It started with a team at Connextra in London and was mentioned at XP2003. I started using it then and wrote about it in my 2004 book, User Stories Applied.

(6) Thanks to Jennifer Fawcett of Tendril Networks for providing these examples  


About the Authors

Dean Leffingwell is an entrepreneur, software executive, consultant and author who provides product strategy and agility coaching to large software enterprises.  Mr. Leffingwell formerly served as chief methodologist to Rally Software and as Vice President of Rational Software, now IBM’s Rational Division, where his responsibilities included the Rational Unified Process. Mr. Leffingwell has been a student, coach and author of contemporary software engineering and management practices throughout his career. His most recent book is Scaling Software Agility: Best Practices for Large Enterprises. His next book, Agile Requirements: Lean Requirements Practices for Teams, Programs and the Enterprise, will be published in 2010. He is also the lead author of the texts Managing Software Requirements: First and Second Editions, both by Addison-Wesley. He can be reached through his blog at www.scalingsoftwareagility.wordpress.com.

Pete Behrens is the Founder and President of Trail Ridge Consulting, a firm specializing in enterprise-wide agile transitions and adoption. Certified as a Scrum Trainer (CST), Scrum Coach (CSC), and Leadership Agility 360 Coach (LA360), Pete enables high-performing adaptive environments through a focus on leadership and organizational agility. As an active member of the agile coaching community, Pete led the development of the Certified Scrum Coaching (CSC) program for the Scrum Alliance. Pete has over 19 years experience guiding product development and architecture in adaptive, iterative and phased-based approaches at EDS, Rational Software and others. He led development of RequisitePro, the leading requirements management solution in the IBM Rational product line and has extensive experience building solutions under the Rational Unified Process (RUP), Rapid Application Development (RAD), as well as traditional phased-based approaches.


Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}