Requirements have been written using many formats. In most cases the “User Story” format is best. This article describes how to write in the “User Story” format. It also offers guidelines for choosing another format.

Who does this practice

Everyone who writes requirements needs to choose the best requirement format.

What to do

Inputs

Inputs to this practice include:

• A requirement to be decomposed
• Information about the requirement to be decomposed: Level (Capability, MBI, Feature, Story), details about the value being developed (customer, Business), and the context in which it is being developed (interfacing systems, technology constraints, etc.)

Approach

The “User Story” format can be used to capture a single scenario, an example of some behavior of the feature, or even reminders or triggers to have a future conversation.

Choosing the best format for a requirement is based on judgment. Judgment comes from experience with requirements decomposition as well as having an understanding of what kinds of information will be needed by those implementing the next level of detail (either requirements at the next level of decomposition, or the software or human procedures that implement a team-level requirement).

Start by assuming the User Story format will work and try to write the requirement using it. If the User Story format does not adequately capture and communicate the requirement, consider alternate formats.

If the User Story format is not capturing every important aspect of the requirement, someone with experience at the next level of detail (or the one below it) should be consulted to find out what they will need to know to do their work successfully. Then pick or develop a format to replace or supplement it.

Tools and techniques

Tools do not usually influence which requirements format to use. However, tools can help keep visible the context of a given requirement. This in turn can suggest what information needs to be recorded in the requirement. Consider a mind-mapping tool or a drawing tool that can be used to draw flow, System-of-System, and other relationship diagrams.

General template: User Story

The essential attributes of a requirement written in the User Story format are:

• ID. An identifier used to refer to the story.
• Description. The intent of the story. Here is the most-common template:

As a <user>, I want <some goal> so that I get <business value or functionality>

where:

“<user>” means the role played by the person to whom the new value will be delivered. For instance, “As a bank teller,” might begin a user story for a software capability that eases an aspect of the teller’s work

“<some goal>” means what the system will do for the user. For instance, “I want to be able to scan in my customer’s debit card number”

“<business value or functionality>” means what the new capability does for the user. For instance, “so that I eliminate the time typing in numbers as well as redoing an entry because of a typing mistake; I currently spend an average of two minutes extra work on each transaction because of these activities.”

• Validation Strategy. Every story must have criteria so that the team can know, “Is this story done?”
• Parent and Related Stories. Where did the story come from and what else is it related to?

Alternatives

The Use Case is one of the main alternative formats used for requirements.

The Use Case is best for when more detailed information is needed about how the stakeholders will need to interact with the functionality being added to the system. This can include things like the before and after conditions of the system fulfilling the requirement, alternative and essential actions based on differing conditions when the user invokes the functionality in the requirement, etc.

Use Cases can be used at any level, including capabilities expressing Business or stakeholder goals (these are sometimes called “Business Use Cases”).

The “Fully Dressed” Use Case format, based on the work of Alistair Cockburn, is:

• Title: “an active-verb goal phrase that names the goal of the primary actor”
• Primary Actor: can be a user, or another system
• Goal in Context: statement of the requirement’s goal and the conditions around the system when its functionality is invoked
• Scope: of the system into which the Use Case is being implemented
• Level: of abstraction of the “goal” or requirement
• Stakeholders and Interests
• Precondition: assumed condition of the systems around the target system
• Minimal Guarantees: critical interests protected in any situation
• Success Guarantees: state of the world around the target system, if the goal is achieved
• Trigger: event that kicks off the Use Case
• Main Success Scenario: interactions between primary actor and target system, from trigger to goal
• Exceptions: what to do when the steps in the scenario are interrupted
• Extensions: additions to the steps in the scenario, for different conditions than assumed in the main success scenario
• Technology & Data Variations List: step variations

The main benefit of the Use Case format is as a list of additional information to add, to augment a User Story formatted requirement.

The main danger in the Use Case format is in making implementation decisions earlier in the development process than they are needed. For instance, it is tempting to specify the steps of interaction between the primary actor and the system in too much detail, before enough is known about the project to allow choreographing those steps for best effect.

• Tabular: When there are a number of different conditions and outcomes, that are naturally represented in table form
• Graphic: When the desired outcome is hard to describe with words, but easy to illustrate with graphics

Outputs

Output from this practice is requirements about which every aspect of importance is expressed, but which contain no unnecessary information such as premature design decisions.

When to do this practice

At every level of requirements decomposition.

Where to do this practice

This practice is not specific to any location.

Outcomes

Following this practice will improve the quality of requirements. Such requirements will:

• Introduce detail and decisions only as needed
• Contain all the information needed at each stage, and only that information
• Avoid constraining the implementation prematurely, before all the information needed to make decisions is known