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

[article]
Summary:

Russell Pannone and Geoffrey Bourne write that at first glance, a User Story looks simple, almost trivial. However, it contains the essence of the project deliverables. It describes the who, the what, and the why of every piece of delivered functionality.

This article is part two of a two-part article excerpted from an upcoming book, being written by Russell Pannone and Geoffrey Bourne to be published by Addison-Wesley. This will be the first book to provide agile-lean product development practitioners with a pragmatic, clear, and concise collection of answers to their questions about agile and lean product (system-software) development.

In Part 1 we covered:

  • The tie between writing agile requirements using stories and an agile requirements positioning statement
  • What is a user story
  • Why user stories

 In Part 2 we will cover:

  • Writing a user story
  • How much detail you need
  • Writing acceptance criteria
  • Running a story brainstorming session

Writing a User Story
At first glance, a User Story looks simple, almost trivial. However, it contains the essence of the project deliverables.  It describes the who, the what, and the why of every piece of delivered functionality.

The typical format for a User Story is:

As a <who/role> I want <what/action> so that <why/reason>.

 As in any good requirement, the User Story contains “what I want.”  However, more often than not requirements forget the all-important “who wants it” and “why.”   Defining the “first person” who/role puts you in the shoes of the user wanting the Story and guides you in asking the right questions about the context and reason for the request. This leads to clarity of the Story’s value and bounding its scope by defining the “why/reason.”

Hopefully you can see the above requirements leave a lot of unanswered questions.  Now let’s look at some examples of well-written User Stories based on the Soulful Winery vision document contained in Appendix A:

  • As a site-administrator, I want to be able to add, change and delete wine lists so that current wine information is displayed on the website.
  • As the application, I want to track all changes for each customer, so that there is an audit trail available at any time.

Note: As depicted above the “who” does not always have to be from a person’s point-of-view.  The who can represent a non-human role that interacts with the product (system-software).

  • As a customer, I want to be able to enter my billing information, so that I can purchase wine from the winery website.
  • As a customer, I want to be able to see my discounts after I make my wine selections, so that I can verify I received the correct discount.
  • As a customer, I want to view a list of wines, so that I can see what's available for purchase.
  • As a customer, I want to be able to select wine by different categories, so that I can specify the wine variety I wish to purchase.
  • As a customer, I want to be able to enter my shipping information, so that the winery can deliver my order to my address of choice and knows where to ship my order.

Note: I if the why/reason is intuitively obvious it can be omitted, but do not do this hastily. If the why/reason is not understood there is a very good chance the Story does not represent a needed value-adding feature.

How Much Detail Do You Need?
One of the challenges you will face is learning how to include just enough detail to minimize ambiguity and uncertainty. The more experience you have working with Stories the easier this will become.

A Story should contain just enough detail to enable the team to determine what the solution involves and what it will take them to deliver the Story.  Anything less makes estimating difficult.  Anything more wastes time and energy on details that will surface during the actual Sprint.

Along the way of discovering and describing Stories you will find a spectrum of Story types: some too big, some too small, and some just right.

A Story that is too big is called an Epic. Epics are difficult to work with because they frequently contain multiple Stories.  When you are sizing your Stories at the Product Backlog level, a Story should contain just enough detail to enable the team to estimate its relative size to other Stories.   Epics are acceptable on the Product Backlog as long as they are Stories at the bottom of your Product Backlog (lowest in priority).  When Epics become the highest priority, break them into smaller and more manageable Stories.

Writing Acceptance Criteria
Writing Acceptance Criteria is one of the most effective ways to represent the details of a Story; leading to a common understanding of Story scope as well as driving out ambiguity and uncertainty.  Let’s create some Acceptance Criteria for our Soulful Winery:

Story

AcceptanceCriteria

As a customer, I want to be able to select wine by different categories, so that I can specify the wine I wish to purchase

  • Verify and validate customer can enter their customer identification
  • Verify and validate a customer’s search and view of wine selection displays current information and correctly
  • Verify and validate when there are errors the correct message is displayed

As a customer, I want to be able to enter my shipping information, so that the winery can deliver my order to my address of choice and knows how to ship my order

  • Verify and validate customer can enter their customer identification
  • For existing customers, display their shipping information when it exists
  • Verify and validate shipping information
  • Verify and validate when there are errors the correct message is displayed

As the application, I want to track all changes for each customer, so that there is an audit trail available at anytime

  • Verify and validate that audit trail data is encrypted to prevent unauthorized access
  • Verify and validate a complete history for any given  transaction is being logged, backed-up and can be displayed upon request by authorized personnel
  • Verify and validate for archival of old transaction data (more than three years old)
  • Verify and validate when there are errors the appropriate people are notified and resolution is tracked

As a site-administrator, I want to be able to add, change and delete wine lists to be displayed on the website

  • Verify and validate only an authorized site-administrator is able to add, change or delete wine lists
  • Verify and validate the wine list displays current information and correctly
  • Verify and validate when there are errors the correct message is displayed

As a company executive, I need to be able to access wine club member information (canned & ad-hoc) so that I can learn about my market/clientele  an increase revenue

 

  • Verify and validate only authorized company executives have access to reports
  • Verify and validate when a report is requested it displays current information and correctly
  • Verify and validate when there are errors the correct message is displayed

 

The Stories defines the who, the what, and the why.  The Acceptance Criteria complements the Story by benchmarking the elements required for success.  The Story is like the blueprint of a building; it sets the direction and goal.  The Acceptance Criteria is like the building’s framework by which all further development relies upon.  Together they make a very strong foundation to design, develop and deliver requirements.

Running a Story Brainstorming Session
The art of bringing people together, face-to-face or remotely, to elicit requirements and gain consensus is a critical success factor in delivering something of commercial or operational business value iteratively and incrementally. I recommend conducting a Story elicitation brainstorming workshop every few weeks to refresh and create new Stories for the Product Backlog. To run a group brainstorming session effectively, do the following:

  • Set up a comfortable meeting environment for the workshop.
  • Appoint one person to record what comes from the workshop.
  • If people aren’t already used to working together, use a warm-up exercise or ice-breaker.
  • Make it clear that that the objective of the meeting is to identify Stories based on the Product Vision. The details of the what, why, when, and how of the Product Vision is another question and answer included in my upcoming book.
  • Ensure that no train of thought is followed for too long – time-box conversations.
  • Start analyzing who wants what and why within the context of the Product Vision.  Step into the “who’s” shoes to understand their wants and reasoning.  Record what you discover in a table as depicted in Table 1.0.
  • Role playing can be fun, so enjoy the brainstorming exercise.  You’ll be amazed and the insights you’ll discover.

Who (Role)

What (Action)

Why (Reason)

Executive

  • Have administrative privileges to access Wine Club member information; both canned and ad-hoc
  • Learn about winery’s clientele  to  be able to increase revenue
  • Learn about winery’s market to  be able to increase revenue

Customer

  • Browse and order complete selection of wine online; including viewing wine specific information
  • Enter billing information
  • Enter shipping information
  • Update order information; including canceling an order
  • Update Wine Club membership information
  • Sign up for e-newsletter
  • Secure login/logout

 

  • See what's available for purchase
  • Specify the wine I wish to purchase
  • Deliver orders to address of choice
  • Knows where to ship order
  • Get current winery news
  • Keep my membership current
  • Manage my membership

Site-Administrator

  • Add, change and delete wine lists
  • Add, change and delete customer information
  • Add, change, and delete company information
  • Current wine information is displayed on the website
  • Current authorized customer information is displayed on the website
  • Current winery information is displayed on the website

Application

  • Track all changes for each customer
  • Need audit trail available at anytime for all transactions

 

Table 1.0 – Story Brainstorming

Final Thought
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 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 User 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.

About the Authors
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. 

Geoffrey Bourne has over 13 years of experience in the financial IT field, having worked at J.P. Morgan, Goldman Sachs and several start-ups.  He has spent many years managing globally distributed Agile teams, and is the co-author of the upcoming Addison Wesley book Agile Answered.  He has a B.S. in Computer Science from Washington & Lee University and is a certified Sun Java Developer and PMP.  Geoffrey is currently a Senior Vice President at a major financial institution in New York City and manages the Private Bank, Personal Wealth Management, and Corporate Agile mobile groups. 

About the author

CMCrossroads is a TechWell community.

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