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 to this practice include:
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:
As a <user>, I want <some goal> so that I get <business value or functionality>
“<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.”
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:
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.
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.
Following this practice will improve the quality of requirements. Such requirements will: