New to User Stories?

Written for the Scrum Alliance. A CSPΓÇÖs perspective on user stories, requirements, and use cases

19 April 2010

William Nazzaro
Process Synergy, LLC

Having coached traditional requirements, use cases, user stories, and agile development, I’ve fielded a lot of questions around the differences among the three major ways of specifying requirements, particularly by people migrating to user stories. To set the record straight on requirements, use cases, and user stories, I will describe each methodology and then compare the three against each other.

Traditional requirements

Traditional requirements are criteria to which the system or business must adhere. They are usually created before the coding begins and are nearly always written as text. They often are thought of as constraints, conditions, or capabilities to which the system must conform. 

Good requirements have the following characteristics:

  • Complete. Requirements should be as complete as possible—no open-ended requirements.
  • Testable. Must be able to create a test for all requirements.
  • Consistent. Requirements must be consistent with each other—no conflicts.
  • Design Free. Software requirements should be specified in the business perspective rather than the software perspective. 
  • Unambiguous. Use "shall" and other related words. Don’t be wishy-washy.

Traditional requirements focus on system operation. They typically are written in such a way as to limit interpretation and rarely contain explicit tests or acceptance criteria.  These types of requirements are often written atomically; meaning that thousands of independent shall statements can comprise a software requirements specification.  Traditional requirements are normally treated as a contract between the business and systems development and, as such, completeness, formality and rigidity in requirements is the rule. 

Use Cases

A use case is a series of interactions by the user (Actor) with the system and the response of the system. Use cases consist of two main components: use case diagrams (which graphically describe actors, use cases, system boundaries, and the relationship between all of these) and the text of the use case itself.  Use cases and use case diagrams focus on the user, with a use case text itself written in a call-and-response format that shows an action by the user, followed by the system’s response.  

Use cases focus on interactions and are written in such a way as to succinctly define the user/system activities and data that define the interaction. Use cases can be written atomically as well, but the use case diagram is meant to tie together the use cases. Use cases are intended to be drilled down in successive levels of detail, reducing the need for nailing down the details before coding. 

User Stories

User stories are actually narrative texts that describe an interaction of the user and the system, focusing on the value a user gains from the system.  A true user story is a metaphor for the work being done.  It is not a highly documented requirement but rather a reminder to collaborate about the topic of the user story—in other words in agile development (good agile at least), the documentation is secondary to the collaboration.  User stories aren’t agile in and of themselves. Instead, their underlying agile values—collaboration and just-in-time definition—make user stories a good agile tool.  Formality is specifically removed from the mix and specification of the user story is pushed as late as possible. 

A good user story uses the “INVEST” model:

  • Independent. Reduced dependencies  = easier to plan
  • Negotiable. Details added via collaboration
  • Valuable. Provides value to the customer
  • Estimable. Too big or too vague = not estimable
  • Small. Can be done in less than a week by the team
  • Testable. Good acceptance criteria
User story–writing process

The story-writing process is integral to understanding user stories. 

The typical template has 3 parts: the title, the description (or body of the user story), and the acceptance criteria.  The title is used to reference the user story and should be kept very short, around 3 to 10 words.  The description is where the meat of the user story is kept.  It is the only part that can be explained as a reasonable template. The acceptance criteria are used to determine when the user story has met the goal of the user – a sort of test.

Start by writing the title.  It should be long enough to allow people on the team to differentiate it from other stories but short enough to fit on a 3” x 5” sticky card when written with a marker. 

Now write the description. You can use the following template:
As a [user role] I want to [goal] so I can [reason]. 

If the description becomes lengthy (more than will fit on an index card), you should revisit the user story. It is likely it needs to be split into several stories. You might also consider whether you are trying to include too much detail. Remember that the purpose of a user story is to encourage collaboration. A user story is a promise to have a future conversation; it is not meant to document every aspect of the work, as you might in a series of traditional requirements statements.

When writing a user story, you might include some acceptance criteria, perhaps in the form of a test case or a brief description of "done," if those criteria help make the intent of the user story easier to remember. When the team is ready to work on that story, however, the team and the product owner must discuss the user story. This process will include (indeed must include) adding acceptance criteria so the team will know what done means. Later, as the team members begin to work on the story, they might contact the product owner and discuss new/different acceptance criteria as their understanding of the story grows – acceptance criteria enrich the understanding of the story, which in turn brings out new acceptance criteria and more meaningful conversations about what the customer really wants.

Frequent Mistakes in User Stories

There are three main problems I see in stories.  First is too much information in the description.  This leads to a loss of collaboration and a reliance on the old ways of documenting everything. A user story should be thought of as a "talking points", a "to-do list," or a "tickler that a conversation must occur about a topic."  The user story is a placeholder for a conversation or series of conversations: it is only through collaboration that a user story works as an agile tool; otherwise it's just a requirement written on an index card.

Too much information in a description can lead to the second problem: missing information in acceptance criteria. Before agreeing to work on a story, the team must understand the acceptance criteria. These are essential for knowing what needs to be done in order to satisfy the user story. Acceptance criteria should be detailed enough to define when the user story is satisfied, yet not so detailed as to quash collaboration. Writing acceptance criteria should not an afterthought – it is a crucial part of a user story.

The third problem is to confuse acceptance criteria and test cases. Both are necessary for a user story. Acceptance criteria answer the question, “How will I know when I’m done with the story?” Test cases answer the questions, “How do I test and what are the test steps?”  While both acceptance tests and test cases should be added to the user story via collaboration, only acceptance criteria are required. Test-driven development is often used to flesh out the test cases as the code is written.

Comparing User Stories, Use Cases, and Requirements

The basic difference between user stories and other forms of requirements specification has to do with perspective and intent, both of which affect the level of detail.

Traditional requirements’ perspective is on system operations. They are typically written with the intent of limiting interpretation. They rarely have tests or acceptance as part of the mix – that’s another document – and are often written by someone other than the requirements author.  The level of detail can vary, particularly if those writing the requirements are using a hierarchical approach to drill down to successive levels of detail. Traditional requirement focus on what the system should do, not on the user or business workflow.

Use cases have the perspective of the users and their interaction with the system in mind.  The use case diagram and associated text are intended to show the capabilities of the user and how these capabilities are met via a system response. Work flows or business flows can be derived from use case diagrams; the text of the use cases shows system and user interaction in a call-and-response format. Use case text typically contains more details than stories and traditional requirements. Test cases can often be written from the use case text, but are not typically part of the use case diagram per se. 

Both traditional requirements and use cases are meant to be successively refined into greater detail through detailed analysis and design into. They are both written as the primary communication media for the system capabilities.    

User stories focus on customer value. They don’t just assume a looseness of specification; they actually encourage it in order to foster a higher level of collaboration between the stakeholders and the team. A user story is a metaphor for the work being done, not a full description of the work.  The actual work being done is fleshed out via collaboration revolving around the user story as system development progresses. As such the level of detail of a user story is ultimately higher than a use case but lower than a traditional requirement. In order to limit scope, user stories have collaboratively developed acceptance criteria which define when the user story meets the stakeholder’s expectations.  Test cases are often developed as code (with test driven development) or documented as the code is developed.

Comparison example

Problem Statement
The client has requested the ability to search for health care providers by provider specialty within a doctor selection site.

Sample Requirements Statement:
The provider search screen shall provide the ability to search for providers by provider specialty.

Sample Use Case
The client selects provider search.
The system retrieves a predefined list of provider specialties and populates the specialty list. The system displays the provider search mechanism. 

The client selects a provider specialty and initiates the search. 
The system retrieves a list of providers that match the provider specialty search. [Alt 1]
The system displays a list of providers that match the search. [Alt 2]
End use case

Alt 1:  If there are no matches, the system displays a message indicating that no matches were found.  End use case.

Alt 2:  If there are more matches than the user can view, the system will provide the capability to display multiple pages.

Sample User story
Title:
Search for providers by provider specialty.

Description:
As a provider search user, I need the ability to search for providers by specialty so that I can more efficiently refer patients to specialists.

Acceptance criteria:
The provider search mechanism has the ability to enter a specialty.
The specialty search will have a list of provider specialties from which to select.
Searching via the provider specialty will return a list of matching specialists or a message indicating that there are no matches.
If there are more results than can fit on one page, the system will provide the capability to view the list in pages or sections.

Conclusion

Are user stories better than other types of requirements specification? It depends. In the end, it’s the individual or team that makes a particular technique work (or fail). If a team is used to an iterative approach, use cases and user stories will be relatively easy to work with.  If a team is steeped in waterfall and “big requirements up front (BRUF),” that team likely will bring that style to user stories and end up with traditional requirements that are user stories in name only. Adopting the underlying philosophy (concepts like collaboration and just-in-time requirements) is the key to moving toward more agile specification devices, such as user stories.

User stories are not a highly documented series of requirements but rather a reminder to collaborate about the topic of the user story—in other words, in agile development (good agile at least), the documentation is secondary to the collaboration. The intent of user stories is to foster collaboration; the perspective is on customer value. If your user stories look more like requirements in disguise, you need to worry less about what specification you are using and more about how to increase collaboration. If, on the other hand, you have a collaborative environment already, user stories will enhance the collaboration more than use cases and traditional requirements can, in which case user stories are a better tool for you.

Article Rating

Current rating: 4.2 (5 ratings)

Comments

Henri Stegehuis, CSP,CSM, 4/26/2010 6:52:29 AM
I agree with the fundamental idea of this article. Good to bring things into perspective! Thanks for that. Important to stress out is the fact that user stories strongly rely on domain expertise (mature team members). If the perspective and intend are not in the team, the outcome will be hard to get in line with expectations.

With respect to user stories and requirements I have a little different opinion. As long as it is not BRUF I think that using a couple of requirements to indeed limit the scope but taking the domain expertise into account, can help the customer (PO) on acceptance level both in understanding and playing a role in the acceptance (Test Driven Design should be based on some requirements of the user story). A traceability matrix helps in regression testing and user acceptance (apart from the fact that different processes demand traceability). What I agree up-on is the fact that these requirements are part of the story realisation and not somewhere far in advance by somebody not being committed. But as stated before, I think these "derived user story requirements" are a minor difference in opinion.
Mia McCroskey, CSP,CSM, 5/25/2010 3:38:03 PM
The fundamental differences in approach among these requirement types is well stated here, and it's key to the value of scrum.

I'm a scrum master in a two-team shop, as well as the chief business analyst for both and the QA manager. Early on in our adoption of Scrum we realized that we couldn't remember what we'd done on a particular feature a couple sprints back, and couldn't remember which user story it was part of.

I had (stubbornly) continued to update our the requirements and business rules in our requirements model (but not the use cases) with the formal conditions of acceptance from the user stories as well as emergent and derived requirements (i.e., decisions) during each sprint. So I, or any team member, can go to the functionally organized model and find what we decided when we did the work.

We continue to maintain traceability from codeset through test, requirements, and rules right up to the user story.

We definitely document far fewer requirements than we did when we tried to make all the decisions up front -- partially because we don't capture stuff that turns out to be irrelevant, but also because we don't document any requirement that's covered by a standard.
Nikolaus Rumm, CSM, 8/3/2010 2:43:39 PM
Frankly, I have to disagree in several points:
First of all, 'traditional requirements analysis', according to the IREB standard, goes much further than specifying atomic requirements or use cases. In brief, a software requirements specification contains - besides other important stuff (like the system context) both functional (often defined as use cases) and non-functional (often defined as atomic requirements) requirements. Unfortunately it's the non-functional requirements that drive a system's cost.
Traditional requirements engineering has adopted agile practices quite well, long before SCRUM was even invented. So that's not the major difference between both worlds.

A use case is just a brief description of a product process (which itself is a sub-process of a business process). Usually this process contains alternative paths and several events that trigger it. In all cases this is an end-to-end process, meaning that it origins from an external actor or is time-triggered. The business value is a non-concern with use cases. It's main goal is completeness. A use case's granularity is very coarse. A typical mid-sized system contains some 10-20 use cases, while the same functionality can be described by about one hundred user stories.

A user story on the other side is a description of some functionality along with it's business purpose. Some add non-functional requirements (as constraints) and most user stories contain acceptance criteria. The granularity is fine , much finer than that of a user story.
I agree that a user story is some kind of placeholder for marking that the team has to do something in the future, but it's never a complete set of requirements, even with the best collaboration done. It's contents might be sufficient for the project's duration but a set of user stories is far from being sufficient for maintainance.

User stories are very well suited for agile development, as they are handy, easy to add/edit/drop and - in most cases - understandable by the customer. Furthermore they are - enriched with priority and an estimation - drivers for the project schedule. From the project's point of view a user story is a mixture of a set of requirements and a lightweight contract that someone has to do something.

The problem with user stories is that they usually lack completeness. This might not be a problem for the developers that use direct customer-contact and collaboration for clarifying requirements, but it's a nightmare for testers (meaning: the real testers, not the unit tests that are written by developers).
Charles Bradley - Scrum Coach, CSP,CSM,CSPO, 5/4/2012 5:13:21 PM
@Nikolaus,

Your last two sentences indicate to me that you are not executing the User Stories practice correctly, nor well. User Stories only lack completeness if the team lets them lack completeness. Further, any developer who is clarifying requirement details should involve the tester as well, or at the very least communicate the decisions that were made by the PO/Customer. I think your team needs to focus more on individuals and interactions.

The level of detail required in a user story is totally dependent on the team, application, and story. Testers should always be involved in story grooming to the utmost extent possible.
Charles Bradley - Scrum Coach, CSP,CSM,CSPO, 5/4/2012 5:16:52 PM
William,
[quote]When the team is ready to work on that story, however, the team and the product owner must discuss the user story. This process will include (indeed must include) adding acceptance criteria so the team will know what done means.[\quote] There is no requirement in the User Stories practice that the team and PO must discuss the user story when development begins. This is often useful, but not required. Further, adding acceptance tests can(and should) be largely done before development begins. I discuss this and other user story topics on my web site here: http://www.scrumcrazy.com/User+Story+Basics

You must Login or Signup to comment.