Functional Analysis with User Stories
The other functional analysis recipes in this chapter are fairly rigorous and use executable models to identify missing and incorrect requirements. User stories can be used for simple use cases that don’t have complex behaviors. In the other functional analysis recipes, validation of the use case requirements can use a combination of subject matter expert review, testing, and even formal mathematical analysis prior to their application to the system design. User stories only permit validation via review and so are correspondingly harder to verify as complete, accurate, and correct.
A little bit about user stories
User stories are approximately equivalent to scenarios in that both scenarios and user stories describe a singular path through a use case. Both are “partially constructive” in the sense that individually, they only describe part of the overall use case. User stories do it with natural language text, while scenarios do it with a SysML sequence diagram. The difference between user stories and scenarios is summarized in Figure 2.47:
Figure 2.47: User story or scenarios
User stories have a canonical form:
“As a” <user> “I want” <feature> “so that” <reason>|<outcome>
A few examples of user stories are provided in Chapter 1, Basics of Agile Systems Modeling, in the recipe for Estimating Effort, such as:
User Story: Set Resistance Under User Control:
As a rider, I want to set the resistance level provided to the pedals to increase or decrease the effort for a given gearing, cadence, and incline so that the system simulates road riding effort.
Each user story represents a small set of requirements. A complete set of user stories includes all or most requirements traced to by the use case.
In SysML, we represent user stories as stereotypes of use cases and use the «include» relations to indicate the use case to which the user story applies. The stereotype adds the acceptance_criteria tag to the user story so that it is clear what it means to satisfy the user story. An example, relating a use case, user stories, and requirements, is shown in Figure 2.48:
Figure 2.48: User Story as a stereotype of use case
User Story Guidelines
Here are some guidelines for developing good user stories:
- Focus on the users.
Avoid discussing or referencing design, but instead, focus on the user-system interaction.
- Use personae to discover the stories.
Most systems have many stakeholders with needs to be met. Each user story represents a single stakeholder role. Represent all the users with the set of user stories.
- Develop user stories collaboratively.
User stories are a lightweight analytic technique and can foster good discussions among the product owner and stakeholders, resulting in the identification of specific requirements.
- Keep the stories simple and precise.
Each story should be easy to understand; if it is complex, then try to break it up into multiple stories.
- Start with epics or use cases.
User stories are small, finely-grained things, while epics and use cases provide a larger context.
- Refine your stories.
As your understanding deepens and requirements are uncovered, the stories should be updated to reflect this deeper understanding.
- Be sure to include acceptance criteria.
Acceptance criteria complete the narrative by providing a clear means by which the system design and implementation can be judged to appropriately satisfy the user’s needs.
- Stay within the scope of the owning epic or use case.
While it is true that in simple systems, user stories may not have an owner epic or use case, most will. When there is an owner epic or use case, the story must be a subset of that capability.
- Cover all the stories.
The set of user stories should cover all variant interaction paths of the owning epic or use case.
- Don’t rely solely on user stories.
Because user stories are a natural language narrative, it isn’t clear how they represent all the quality of service requirements. Be sure to include safety, reliability, security, performance, and precision requirements by tracing the user story to those requirements.
Purpose
User stories are a simple way to understand and organize requirements. Most commonly, these are stories within the larger capability context of an epic or use case. User stories are approximately equivalent to a scenario.
Inputs and preconditions
A use case naming a capability of the system from an actor-use point of view.
Outputs and postconditions
The most important outcome is a set of requirements accurately and appropriately specifying the behavior of the system for the use case and acceptance criteria for what it means to satisfy them.
How to do it
Figure 2.49 shows the workflow for this recipe. It is a more informal approach than the preceding recipes but may be useful for simple use cases. Note that, unlike previous recipes, it does not include a behavioral specification in a formal language such as activities or state machines:
Figure 2.49: Functional analysis with user stories
Identify use case
This first step is to identify the generic usage of which the scenarios of interest, user stories, and requirements are aspects.
Describe use case
The description of the use case should include its purpose, and a general description of the flows, preconditions, postconditions, and invariants (assumptions). Some modelers add the specific actors involved, user stories, and scenarios, but I prefer to use the model itself to contain those relations.
Identify related actors
The related actors are those people or systems outside our scope that interact with the system while it executes the current use case. These actors can send messages to the system, receive messages from the system, or both.
State the user stories
This step includes more than creating the “As a <role> …” statements. It also includes creating «include» relations from the owning use case and the addition of acceptance criteria for each user story. If this is the first time this is being done, you will also have to create a «user story» stereotype that applies to use cases to be able to create the model elements, as illustrated in Figure 2.48.
Specify acceptance criteria
Clearly state the criteria that will be applied to the system to demonstrate that the user story is acceptably implemented.
Identify quality of service as requirements
It is very common to forget to include various kinds of qualities of service. This step is an explicit reminder to specify how well the services are provided. Common qualities of service include safety, security, reliability, performance, precision, fidelity, and accuracy.
Verify and validate requirements
For this recipe, validating the requirements is done with a review with the relevant stakeholders. This should involve looking at the use, the set of user stories, the user stories themselves and their acceptance criteria, and the functional and quality of service requirements.
Requirements_change
Parallel to the development and execution of the use case model, we maintain the textual requirements. This workflow event indicates the need to fix an identified requirements defect.
Update requirement set
In response to an identified requirements defect, we fix the textual requirements by adding, deleting, or modifying requirements. This will then be reflected in the updated model.
Add trace links
Once the use case model and requirements stabilize, we add trace links using the «trace» relation or something similar. These relations allow the backtrace to stakeholder requirements as well as forward links to any architectural elements that might already exist. For relations forward to design elements, we generally prefer «satisfy».
Perform use case and requirements review
Once the work has stabilized, a review for correctness and compliance with standards may be done. This allows subject matter experts and stakeholders to review the requirements, use cases, and user stories for correctness, and for quality assurance staff to ensure compliance with modeling and requirements standards.
Example
Identify use case
For this recipe, we will analyze the Emulate DI Shifting use case. In many ways, this use case is an ideal candidate for user stories because the use case is simple and not overly burdened with quality-of-service requirements.
Interested readers can learn more about DI shifting here: https://en.wikipedia.org/wiki/Electronic_gear-shifting_system.
Describe use case
The use case description is shown in Figure 2.50:
Figure 2.50: Description of the emulate DI shifting use case
Identify related actors
The only actor in this use case is the Rider, as shifting gears is one of the three key ways that the Rider interacts with the system (the other two being pedaling and applying brakes).
State the user stories
Figure 2.51 shows the three identified user stories for the use case: using buttons to shift gears, handling gearing crossover on upshifting, and handling gearing cross-over on downshifting:
Figure 2.51: Emulate DI shifting user stories
Specify the related requirements
As these are simple user stories, there are a small number of functional requirements. See Figure 2.52:
Figure 2.52: Emulate DI shifting functional requirements
Identify quality of service as requirements
The previous step specified a small number of requirements but didn’t clarify how well these system functions are to be performed. Most notably, performance and reliability requirements are missing. These are added in Figure 2.53, shown this time in a requirements table:
Figure 2.53: Emulate DI Shifting QoS and Functional Requirements
Verify and validate requirements
The next step is to validate the user stories and related requirements with the stakeholders to ensure their correctness and look for missing, incorrect, or incomplete requirements.
Requirements_change
During this analysis, a stakeholder notes that nothing is said about how the system transitions between mechanical shifting and DI shifting. The following requirements are added:
- The system shall enter DI Shifting mode by selecting that option in the Configuration App.
- Once the DI Shifting mode is selected, this selection shall persist across resets, power resets, and software updates.
- Mechanical shifting shall be the default on initial startup or after a factory-settings reset.
- The system shall leave DI Shifting mode when the user selects the Mechanical Shifting option in the Configuration App.
Update requirements set
The requirements are updated to reflect the stakeholder input from above.
Add trace links
Trace links from both the use case and user stories to the requirements are added. These are shown in diagrammatic form in Figure 2.54.
Note: the figure does not show that use case Emulate DI Shifting traces to all these requirements just to simplify the diagram:
Figure 2.54: Emulate DI Shifting trace links
Perform use case, user story and requirements review
With the analysis complete and the requirements added, a review can be conducted to evaluate the set of requirements. This review typically includes various subject matter experts in addition to the project team.
