How Do I Write Requirements Using Stories and Acceptance Criteria?—Part One


Russell Pannone writes that knowing what comes before the writing of stories, what comes after the writing of stories, and who is going to consume the stories sets the context for the form and substance of a story.

This is part one of a two-part article excerpted from a book I am writing to be published by Addison-Wesley. The book will be the first book to provide agile-lean product development practitioners with a pragmatic, clear, and concise collection of answers to your questions about agile and lean product (system-software) development.

I imagined a user grabbing another user in the hallway and saying, ‘I gotta tell you about this wonderful new thing the application does… ’ Stories are the Stories customers wish they could tell about the system but can’t (yet).”

– Kent Beck

How do you define your project and business requirements?  Do you use the classic method of creating a Business Requirements Document (BRD) early in the project regardless of the project length?  How has that worked for you, especially on a 6-month or year-long project?  Did you need BRD change requests during the project because the team discovered new information, market conditions changed, or someone had an even better idea?  Agile has a different take on the concept of requirements.  Instead of presciently scribing the exact requirements for the project, and compensating for all eventualities, Agile recommends creating a vision of the product, succinct bite-size statements of business value from the Customer’s or Business Partner’s point-of-view, and criteria to verify the delivery completeness; or in Agile terminology, a Product Vision, Stories, and Acceptance Criteria.

Knowing what comes before the writing of stories, what comes after the writing of stories, and who is going to consume the stories sets the context for the form and substance of a story. 

The Tie between Writing Agile Requirements using Stories, the Product Vision and an Agile Requirements Positioning Statement
"If you don't know where you are going, that's where you'll end up.”

-Yogi Berra

A Product Vision and an Agile Requirements Positioning Statement should exist prior to writing agile requirements using stories.  The product vision forms the bedrock for writing agile requirements using stories, and drives the iterative and incremental delivery of commercial or operational value.

One of the key characteristics of the product vision is its focus on describing commercial or operational business value instead of the mechanics of how that value is delivered. An agile-lean product development and delivery team divorced from context can produce very erratic and unpredictable results. The product vision serves as a mechanism to provide context and as a result ground the product development effort in reality. The details of why the Product Vision is important when writing agile requirements using stories is another question and answer that will be included in my upcoming book.

The Agile Requirements Positioning Statement defines the need, belief, and the readiness of the individual, team and organization to do what it takes to effectively elicit and write agile requirements and in turn deliver commercial or operational value. The Agile Requirements Positioning Statement ensures unanimity of purpose within the enterprise and the agile product development and delivery teams by serving as a reference point, educational value, and motivating force:

Reference Point
It guides by providing a common understanding of purpose between the business and the product development team.

Educational Value
It educates people about the common goals and objectives for writing agile requirements. When everyone is able to understand the overall approach a kind of unity of purpose is achieved.

Motivating Force
It offers a roadmap to all team members. They draw meaning and direction from it. Targets are set, work is committed to and team members can now compare themselves against the benchmark set by the agile-lean requirements positioning statement. They can unilaterally change direction whenever they go off the track and set everything along right paths.

Here is an example of an agile requirements positioning statement:

Agile Requirements Positioning Statement


  1. System-software development can only deliver what people ask for and what the developers understood the request to mean; which in the end, more often than not, does not deliver what the people really wanted.
  2. The traditional approach is to attempt to document the requirements for the whole product and then freeze the requirements to provide a stable base for development to proceed. The assumption is we can come to a complete understanding of the product (system-software) before developing code. This is a risky assumption to make for most system-software products high in risk, uncertainty and complexity.

Tenets - Guiding Principles

  1. We recognize and acknowledge the final product evolves during its development and we must positioning ourselves to adapt to change
  2. We realize trying to document all requirements and freezing requirements during early project phases will either cause rework or the delivery of a product that does not meet the Customer needs.
  3. The minimum key Agile requirement artifacts are a Product Vision,  Stories and a prioritized and sized Product Backlog; managed and owned by the Business Partner or Customer.

Enactment – Make it So

  1. Fundamentally, our approach is building product features iteratively and incrementally by Business Partners and IT working collaboratively; built around a key assumption – we continue to learn about the product during the project.
  2. Leveraging effective collaboration between who possess requisite knowledge, authority and responsibility for the requirements, the Business Partner, and who possess the craftsmanship for delivering on the requirements, the Development Team.

What is a Story?

Stories form the bedrock for communicating agile product development requirements. A story is a central part of the iterative and incremental development and delivery of commercial or operational value.  A story makes possible delivering value early and often by focusing on effectively communicating the underlying business requirement and value instead of the delivery mechanism.

Ron Jeffries, one of the creators of Extreme Programming (XP), described what has become the de-facto standard way to think about stories. Ron used the alliteration of card, conversation, and confirmation to describe the three elements of a story:

  • Card - represents the two to three sentences used to describe the intent of the Story.
  • Conversation - represents fleshing out the details of the intent of the card in a conversation with the customer or Product Owner.
  • Confirmation - represents how the team, via the customer or customer proxy, comes to verify that the code meets the full intent of the Story.

A good story is negotiable, testable, possible to estimate, commercially or operationally value adding, cohesive, and loosely coupled.  It is not an explicit contract for features or functionality.

A Story is:

  • “A simple, clear, and brief description of functionality told from the perspective of a user [e.g. Product Owner]” (Cohn, 2010).
  • Aligned against a business value.
  • Refined in successive conversations between the Product Owner and the Development Team.
  • Leverages effective collaboration between those who possess requisite knowledge, authority, and responsibility for the requirement, the Business or Customer, and those who possess the craftsmanship for delivering on the requirement, the Development Team, resulting in commercial or operation value.

But Why Stories?
You may be asking, “Aren’t stories just use cases or requirement statements?”  While overlapping features exist, all three have distinct structures and goals.  Stories encapsulate discreet units of functionality with the longevity of a single iteration/sprint.  On the other hand, use cases contain larger units of work composed of many stories and typically last longer than a single iteration/sprint.  Requirement statements go a step further by documenting every requirement in the minutest detail – ever had a 200+ page requirements document?

Mike Cohn, one of the most distinguished Agile authors, describes three main advantages of stories:

Verbal Communication
Which do you think is more precise, verbal or written communication?  The best form of communication depends upon the context and purpose of the message.  If you can detail all aspects of the requirements in clear and precise language, removing all misconceptions on the part of the reader, please write detailed requirements.  However, if you believe understanding and clarity comes from questions, feedbacks, and non-verbal communication cues, look to create stories.

Cohn gives a wonderful example of the imprecision of written communication:

At lunch recently I read this on my menu: “Entrée comes with choice of soup or salad and bread.”  That should not have been a difficult sentence to understand, but it was. Which of these did it mean I could choose?

  • Soup or (salad and bread)
  • (Soup or salad) and bread

We act as though written words are precise, yet they often aren’t. Contrast the words written on that menu with the waitress’ spoken words: “Would you like soup or salad?” Even better, she removed all ambiguity by placing a basket of bread on the table before she took my order.

Essential for Estimating
Have you ever tried to estimate or project plan from a thick, unwieldy requirements document?  You probably have and I find it to be a difficult guesstimating task.  I often take the requirements doc and break it down into bite-sized chunks just so I can estimate.  Luckily, stories naturally come in digestible units.  By breaking functionality into manageable Sprint length stories you can accurately estimate and prioritize the work.

Just Enough Detail
Details can be dangerous, especially if those details are not immediately important and might change over time.  A Sprint’s stories need details – discovered during the Sprint Planning session and subsequent Sprint.  However, stories remaining on the Product Backlog might or might not make it to the Sprint Backlog.  Save time (and angst if requirements change) by capturing the functionality wanted (i.e. the story) and defer the details until required.

For more details, see Mike Cohn’s article Advantage of User Stories for Requirements.

Traditional system-software development attempts to first document all of a product’s requirements and then freeze those requirements for the duration of the project. The assumption is we can come to a complete understanding of the product (system-software) before developing code. More often than not, dynamic business environments, incomplete project/requirements knowledge, and inherent project risk, uncertainty and complexity make static requirements impractical.  What a shame that new and possibly better ideas must be rejected because they weren’t raised during the business requirements phase.

However, Agile has a wonderful technique to overcome the requirement process limitations of traditional software development: the story.  The written words of a story and all the conversation about the story enables the Product Owner and the delivery team to effectively communicate the product features (who, wants what, why).  Requirements can and do change; the iterative nature of Agile allows the team to refocus on new or lower priority stories during every Sprint Planning session.  Thus, in agile when asked for a new feature you will never say, “I’m sorry but that wasn’t in the requirements.”

A story is a means to an end. Stories first and foremost serve as a communication mechanism leveraging effective collaboration between those who possess requisite knowledge, authority and responsibility for the requirement, the Product Owner (aka the Business or Customer) and those who possess the craftsmanship for delivering on the requirement, the development and delivery team. You will find that the more experience you have discovering and writing stories the easier it will become.

Next month, in part two, we will delve into the remainder of this answer focusing on:

  • Getting ready to write stories and eliciting requirements using stories
  • How much detail to capture
  • Writing acceptance criteria


About the Author
Russell Pannone is the founder of We Be Agile and the Agile Lean Phoenix User Group, the Agile-Lean Adoption Lead and Coach at US Airways.

With almost thirty years of system-software development and delivery experience, Russell’s focus is on working side by side with folks on real projects to help them deliver valuable system-software to production early and often. He gives those with whom he collaborates the best opportunity to beat the competition to market, realize revenue, and discover insights that can foster improvement.

About the author

StickyMinds is a TechWell community.

Through conferences, training, consulting, and online resources, TechWell helps you develop and deliver great software every day.