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, the 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 stores 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 SysML sequence diagrams. The difference between user stories and scenarios is summarized in Figure 2.43:
Figure 2.43 – User story or scenarios
User stories have a canonical form:
A few examples of user stores are provided in Chapter 1, Basics of Agile Systems Modeling, in the Estimating effort recipe. Here's one of them.
User Story: Set Resistance Under User Control
Each user story represents a small set of requirements. A complete set of user stories includes almost all requirements traced by the use case.
In SysML, we represent user stories as stereotypes of use cases and use «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.44:
Figure 2.44 – User stories as a stereotype of a use case
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 stakeholder, 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 user 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 need.
- 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 lightweight analytic technique for understanding and organizing 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 in terms of what it means to satisfy them.
How to do it…
Figure 2.45 shows the workflow for this recipe. It is a more lightweight and 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 formal language such as activities or state machines:
Figure 2.45 – Functional analysis with user stories
Identify the use case
This first step is to identify the generic usage of which the scenarios of interest, user stories, and requirements are aspects.
Describe the use case
The description of the use case should include its purpose, 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.
Specify the related requirements
User stories are a way to capture required system behavior from the actor's perspective. They generally represent a small number of textual system requirements. This step enumerates them.
Identify the quality of service 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 the 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 requirement's defect.
Update the requirement set
In response to an identified requirement's 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 are generally backtraces to stakeholder requirements as well as forward links to any architectural elements that might already exist.
Perform a 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 case, and user stories for correctness, and for quality assurance staff to ensure compliance with modeling and requirements standards.
Example
Here's an example.
Identify the 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.
Describe the use case
The use case description is shown in Figure 2.46:
Figure 2.46 – Description of the Emulate DI Shifting use case
Note
Interested readers can learn more about DI shifting here: https://en.wikipedia.org/wiki/Electronic_gear-shifting_system
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 the brakes).
State the user stories
Figure 2.47 shows the three identified user stories for the use case: using buttons to shift gears, handling gearing cross-over on upshifting, and handling gearing cross-over on downshifting. Note this diagram is very similar to Figure 2.44; however, rather than use an icon for the user stories, this diagram uses standard SysML notation. Additionally, the canonical form of the user story in the description and the acceptance criteria in the tag are exposed in comments:
Figure 2.47 – 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.48:
Figure 2.48 – Emulate DI Shifting functional requirements
Identify the quality of service 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.49, shown this time in a requirements table:
Figure 2.49 – Emulate DI Shifting quality of service and functional requirements
Verify and validate the 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 DI Shifting Mode is selected, this selection shall persist across resets, power resets, and software updates.
- Mechanical shifting shall be the default on 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 the requirements set
The requirements are updated to reflect the stakeholder input from earlier.
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.50. Note: the figure does not show that the Emulate DI Shifting use case traces to all these requirements just to simplify the diagram:
Figure 2.50 – Emulate DI Shifting trace links
Perform a 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.
