Why aren't textual requirements enough?

There are many reasons why textual requirements by themselves fail to result in usable, high-quality systems.

First, it is difficult to ensure all the following functionality is present:

• All normal (sunny day) functionality
• All edge cases
• All variations of inputs, sequences, and timings
• All exception, error, and fault cases
• Qualities of service, such as performance, range, precision, timing, safety, security, and reliability
• All stakeholders appropriately represented

Getting that much is a daunting task indeed. But even beyond that, there is an air gap between realizing a possibly huge set of shall statements and actually meeting the stakeholder needs. The stakeholder believes that if the system performs a specific function, then in practice, their needs will be met. Experience has shown that is not always true. Customers often ask for features that don't address their true needs. Further, requirements are volatile and interact in often subtle but potentially catastrophic ways.

We address this issue by capturing requirements both in textual and formal means via modeling. The textual requirements are important because they are human-readable by anyone even without modeling training. The model representation of the requirement is more formal and lends itself to more rigorous thought and analysis. In general, both are necessary.

Definitions

Before we get into the recipes, let's agree on common terms:

• Requirement: A stakeholder requirement is a statement of what a stakeholder needs. A system requirement is a statement of what the system must do to satisfy a stakeholder need. We will focus on system requirements in this chapter. Normally, requirements are written in an active voice using the shall keyword to indicate a normative requirement, as in the following example:

  The system shall move the robot arm to comply with the user directive.

• Actor: An actor is an element outside the scope of the system we are specifying that has interactions with the system that we care about. Actors may be human users, but they can also be other systems, software applications, or environments.
• Use Case: A use case is a collection of scenarios and/or user stories around a common usage of a system. One may alternatively think of a use case as a collection of requirements around a usage-centered capability of the system. Still another way to think about use cases is that they are a sequenced set of system functions that execute in a coherent set of system-actor interactions. These all come down to basically the same thing. In practice, a use case is a named usage of a system that traces to anywhere between 10-100 requirements and 3-25 scenarios or user stories.
• Activities: An activity diagram in SysML is a composite behavior of some portion of a system. Activities are defined in terms of sequences of actions which, in this context, correspond to either a system function, an input, or an output.

  Activities can model the behavior of use cases. Activities are said to be fully constructive in the sense that they model all possible behavior of the use case.

• State Machines: A state machine in SysML is a composite behavior of a system element, such as a block or use case. In this context, a state machine is a fully constructive behavior focusing on conditions of the system (states) and how the system changes from state to state, executing system functions along the way.
• Scenarios: A scenario is an interaction of a set of elements in a particular case or flow. In this usage, a scenario represents a partially complete behavior showing the interaction of the actors with the system as it executes a use case. The reason that it is partially complete is that a given scenario only shows one or a very small number of possible flows within a use case. Scenarios are roughly equivalent to user stories. In SysML, scenarios are generally captured using sequence diagrams.
• User Story: A user story is a statement about system usage from a user or actor's point of view that achieves a user goal. User stories describe singular interactions and so are similar in scope to scenarios. User stories use a canonical textual formulation such as As a <user> I want <feature> so that <output or outcome>.

  Here's an example:

  As a pilot, I want to control the rudder of the aircraft using foot pedals so that I can set the yaw of the aircraft.

  User stores tend to be most beneficial for simpler interactions, as complex interactions are difficult to write out in understandable text. Scenarios are generally preferred for complex interactions or when there is a lot of precise detail that must be specified. Consider the following somewhat unwieldy user story:

  As a navigation system, I want to measure the position of the aircraft in 3 dimensions with an accuracy of +/- 1 m every 0.5s so that I can fly to the destination.

And that's still a rather simple scenario.