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

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:

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.
  
  

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.