2  A Theory of Requirements Engineering - Part I

Theories play a crucial role in engineering: they help engineers understand and improve their practices. The theory in this chapter will help you understand all requirements engineering methods and be more skilled in the practice. At the heart of this theory is the most important formula of requirements engineering:

Req, Dom \(\vdash\) Goals

That formula is so important that some have called it the E=mc² of requirement engineering. The formula implies that requirements engineering involves three kinds of properties:

• Stakeholder goals (Goals), which are desired properties of the world in which the software operates — for example, “an ambulance must arrive quickly in response to emergency calls”;
• Software requirements (Req), which are the desired properties of the software, i.e. its desired externally visible behaviours and qualities;
• Domain assumptions (Dom), which are assumed properties about the context in which the software operates.

The formula defines what it means for software requirements to be “correct” with respect to some goals: the software requirements Req are correct with respect to the stakeholders goals Goals if there exists valid domain assumptions Dom such that it is possible to prove (that is the meaning of the \(\vdash\) symbol) that if the software satisfies the requirements Req, and the world satisfies the assumptions Dom, then the stakeholder goals Goals are necessarily satisfied. We will explain this formula in details, illustrates it on real examples and discuss its implications for practice.

The presentation of this theory is split over two chapters. The first part introduces fundamental concepts that will be used throughout the book and previews some of the modelling techniques that we will use later. The second part will define further concepts, explains the Req, Dom \(\vdash\) Goals formula and its implications for practice.

2.1 The World and the Machine

Like all technical disciplines, requirements engineering has its own specialized concepts and terminology. The first two important concepts are the World and the Machine.

Definitions: The World and the Machine

• The Machine is the product to be developed or improved.
• The World is the part of the real world affected by the Machine.

The Machine is whatever product or service we are in charge of developing or improving. Synonyms for the Machine are the “product”, the “system-to-be”, or the “software-to-be”. Testers also call the Machine the “system-under-test”. The Machine is a concrete object: a physical computer or a set of physical computers that execute instructions described in code. The code transform general-purpose computers into specialized machines. For example, a media player software temporarily transforms general purpose devices (phones, tablets or laptops) into specialized machines that play music and videos. During requirements engineering, it is useful to think of what we produce as tangible machines rather than lines of codes. For those of us who spend most of their days in code, this is a major shift of perspective. Calling what we build “the Machine” helps us remember that even though the code we write is intangible, what we ultimately put into the world are actual machines that have real, tangible effects on people and the environment.

The World is the part of the real world affected by the Machine. The World includes people, objects, devices and other software systems. Synonyms are the “domain”, the “application domain”, the “problem domain”, the “environment” and the “context”. We build the Machine to serve some practical purposes in the World. For example, we build an airplane braking controller to reduce airplane accidents, we build an ambulance dispatch software to reduce ambulance waiting times. The Machine is only a means to an end. What matters are the impacts that the Machine has on the World.

The World is not the entire physical world; it is the part physical world that is relevant to, and impacted by the Machine. For example, if the Machine is a software to control the airplane braking system, the World includes the plane position, whether it is flying or moving on the runway, whether the ground spoilers and reverse thrust are deployed or not, but it does not include the plane passengers, their ages, or what they ate for lunch. All this is irrelevant to the design of the airplane braking system. The World thus defines the scope of our requirements engineering concerns; it separates what needs to be investigated from what can be left out. Deciding this scope is one of the trickiest parts of requirements engineering. We will study techniques supporting such decisions in future chapters.

The World and the Machine are connected to each other. This connection is what allows the Machine to obtain information about the World and produce effects on the World. Without this connection, the Machine would not be able to have any impact on the World.

What do people mean by “the system”?

In practice, people use the words “the system” to refer to either the Machine or the World. A system is a group of interacting elements that work as a whole. The Machine is a system (e.g. the ambulance dispatching software system). The World is also a system (e.g. the ambulance dispatching system composed of human call handlers, ambulance dispatchers, and paramedics). Watch out for misunderstandings when people talk about “the system” as it may not be clear whether they talk about the World or the Machine.

2.2 Phenomena

Requirements engineering involves the gradual transformation of vague concerns (e.g. “The ground braking system must be safe”) into concrete statements of desired properties (e.g. “reverse thrust should not be deployed when the plane is flying”). Asking for the ground braking system to be safe is vague because the concern (“being safe”) is not specific enough: it does not refer to concrete, specific phenomena. Asking that the plane does not crash is a clearer statement of need: we know exactly what observable event is to be avoided. Asking that reverse thrust is not deployed when the plane is flying is also clearer because it refers to specific observable states: the plane flying, and reverse thrust not being deployed.

The trick that skilled requirements engineers use to understand vague concerns and rephrase them into clearer statements of needs is to look for concrete phenomena (observable states and events). This is why the concept of phenomena is so important in requirements engineering: it encourages clear communication by focussing on what is observable.

Definitions: Phenomena, states, events

• A phenomenon (plural: phenomena) is an observable state or event.
• A state is a condition that something or someone is in at a specific time.
• An event is something that occurs at a specific time.

Table 2.1 lists some phenomena for the airplane ground braking system of Chapter 1.

Table 2.1: Phenomena for the airplane braking system

Phenomena	Shorthand notation
the plane is flying	Flying
the plane is moving on the runway	MovingOnRunway
reverse thrust is deployed	RevThrustDeployed

In this table, the phrases on the left are phenomena descriptions, the terms on the right are shorthand notations for these descriptions.

The phenomena in Table 2.1 are all states: the first two are states of the plane, the third is a state of the plane engines.

Phenomena descriptions can be combined to form sentences that describe stakeholder goals, software requirements and domain assumptions. The sentences can be in natural language (e.g. “reverse thrust should not be deployed when the plane is flying”) and, optionally, in formal logic (e.g. Flying => not RevThrustDeployed, where => is the symbol for logical implication). We will see more examples later.

Choosing a set of phenomena is choosing a particular way of looking at the World. For example, by choosing the phenomena RevThrustDeployed, we have chosen to look at the plane’s reverse thrust as being either deployed on both wings or not deployed. We ignore other details such as the engine’s state and the reverse thrust power on each wing individually. This is fine for expressing the need that reverse thrust should not be deployed during flight, but in other situations, we could choose different phenomena. Choosing a useful set of phenomena, one that is appropriate for describing the stakeholder needs, is one of the most important skills in requirements engineering. That skill is often unconscious: people acquire it without realising it.

Domain Conceptual Models: A Preview

One way to catalogue the chosen phenomena is to organise them in a domain conceptual model. These models are described in Chapter 17. As a preview, Figure 2.1 shows a conceptual model with all phenomena in Table 2.1 and a few more phenomena that will be introduced later in Table 2.2.

Figure 2.1: A small conceptual model for the Ground Braking System

In practice, domain conceptual models are often larger, include associations (there are no associations in Figure 2.1), and a variety of attribute value types (not just True/False).

Glossaries can also be used to list and define the phenomena. The use of glossaries will be described in Chapter 9 and Chapter 17.

2.3 Phenomena Location

We classify phenomena based on their location: in the World, in the Machine, or at the intersection between the World and the Machine.

Definitions: World, Machine and Shared Phenomena

• A World phenomenon is a phenomenon located in the World.
• A Machine phenomenon is a phenomenon located in the Machine.
• A shared phenomenon is a phenomenon located at the interface between the World and the Machine.

Figure 2.2 shows examples of World and shared phenomena for the ground braking system.

Figure 2.2: World and Shared Phenomena for the Ground Braking System

All phenomena from Table 2.1 are World phenomena that are not shared with the Machine. Other phenomena relevant to the ground braking system are:

Table 2.2: More phenomena for the ground braking system

Phenomena	Shorthand notation
the landing gears wheels are turning	WheelsTuring
the landing gears wheels sensors signal that the wheels are turning	WheelsPulsesOn
ground braking is enabled	GrdBrakingEnabled

In Figure 2.2:

• WheelsTurning is a world phenomena that is not shared with the Machine (the software controller). It is an important phenomena because the ground barking system uses it as an indicator that the plane is moving on the runway. Whether the wheels are turning is however not directly observable by the software controller.
• WheelsPulsesOn is a shared phenomena. The wheels sensors are connected to the software controller through a wire. The signals sent along that wire by the wheels sensors are perceived by the software controller.
• GrdBrakingEnabled is another shared phenomena. The Machine has the ability to enable and disable the ground spoilers and reverse thrust by sending commands to the actuators that control these components. To enable means to allow, to disable means to prevent. When the ground braking is enabled, it means that the ground spoilers and reverse thrust can be deployed. When ground braking is disabled, the ground spoilers and reverse thrust will not deploy even if the pilot pushes the buttons to deploy them.

Machine phenomena that are not shared with the Machine include internal function calls, internal events, and internal variables states.

Requirements engineering is entirely concerned with World phenomena and should avoid references to internal Machine phenomena, which are concerns for the software internal design and implementation.

2.4 Machine Inputs and Outputs

Among shared phenomena, we distinguish machine inputs and outputs.

Definitions: Machine inputs and outputs

• A machine input is a shared phenomenon controlled by the World.
• A machine output is a shared phenomenon controlled by the Machine.

In our example, WheelsPulsesOn is a Machine input, and GrdBrakingEnabled a machine output.

In programming terms, you can think of machine inputs and outputs as World phenomena that the machine can “read” and “write”, respectively. You can also think of World phenomena that are not shared with the Machine as states and events in the World that the machine has no direct access to: it can neither read nor write them.

It is important however to remember that despite their names, machine inputs and outputs are also World phenomena. During implementation, we think of machine inputs and outputs as Machine phenomena (i.e. in terms of code). For requirements engineering, we need to think of them as World phenomena shared with the Machine.

Synonyms in Systems Engineering

In systems engineering, it is common to consider two machines simultaneously: a larger system-level machine and a smaller software-level machine. The system-level machine contains the software-level machine, input devices (sensors) and output devices (actuators), as shown in Figure 2.3. On the system-level machine, the machine inputs and outputs are also called monitored and controlled variables; on the software-level machine, they are still simply called inputs and outputs. In our example, WheelsTuring would be a monitored variable, and RevThrustDeployed a controlled variable.

Figure 2.3: The Four-Variable Model

The model in Figure 2.3 is called the four-variable model because it has four types of variables: monitored, controlled, input and output.

Sometimes, you will be responsible for writing requirements for a system-level machine; sometimes for a software level machine; and sometimes for both. We will see later that there are relations between system-level and software-level requirements.

Context Diagrams: A Preview

In practice, machine inputs and outputs are commonly represented using context diagrams. We will explain context diagrams in Chapter 16. As a preview, Figure 2.4 shows a context diagram for the ground braking system. The machine in this diagram is the Ground Braking Controller on the right. The other boxes and the stick figure are actors in the World. The next section defines what we mean by actor.

Figure 2.4: A Context Diagram for the Ground Braking System

2.5 Actors and Stakeholders

Two other important concepts are that of actors and stakeholders.

Actors

Definition: Actors

An actor is an entity that can perform actions in the World. An actor can initiate events or change some states in the World.

An actor can be a person, a department or organisation, a device like a sensor or actuator, or a software system. The Machine is also an actor.

When we say that the Machine and other software systems are actors, we do not imply that they are conscious and intelligent like humans. We simply mean that they can perform actions in the World.

Actors for the ground braking system are shown in Figure 2.4. They include the pilot, wheels sensors attached to the landing gears, the actuators controlling the states of the ground spoilers, engine thrust and landing brakes, and our Machine: the Ground Braking Controller.

The concept of actor is present in many requirements modelling languages, notably in use cases, domain scenarios, context diagrams and goal models.

Synonyms for actor are “agent”, “component”, and “element”.

Stakeholders

Definition: Stakeholders

A stakeholder is a person or group of persons who has an interest in, or is affected by the Machine.

As mentioned in Chapter 1, the stakeholders usually includes many more people that the client (who pays for machine development) and users (who operate the machine). For example, airplane passengers are stakeholders of the airplane ground braking system, although they are neither clients nor users. Other stakeholders include aircraft manufacturers, airlines who buy and operate the aircraft, and authorities around the world who supervise and regulate commercial air travels. The software engineering team who develop and maintain the Ground Braking Controller are also stakeholders. All these people (and others) have a stake in the system. Understanding the needs and expectations of all stakeholders is important to build a successful product. We will study how to discover stakeholders and their needs in Chapter 9.

A stakeholder is not the same thing as an actor. Some people are both actors and stakeholders. Usually, all human actors will have an interest in, and be affected by the Machine. They are therefore both actors in the World and stakeholders of the World. Not all actors, however, are stakeholders. Non-human actors, like sensors, actuators and other software systems are not stakeholders (they are not people). The persons who develop, maintain, and sell these systems, however, are likely to be stakeholders. Finally, not all stakeholders are actors. For example, airplane manufacturers, airlines, and the authorities that regulate air travel and certify airplane systems are all stakeholders of the ground braking system, but they are not actors in that system.

2.6 Notes and Further Readings

The theory of requirements engineering presented here has been developed by Pamela Zave and Michael Jackson. The ideas are described in multiple papers. Excellent introductions can be found in “Deriving Specifications from Requirements: an Example” and “The World and The Machine” (Jackson and Zave 1995; Jackson 1995b). A more detailed presentation can be found in the journal paper “Four Dark Corners of Requirements Engineering” (Zave and Jackson 1997). The most enjoyable exposition (and many other insights about software development) can be found in Michael Jackson’s brilliant book “Software Requirements & Specifications" (Jackson 1995a).

In their papers, Zave and Jackson use different notations for the Req, Dom \(\vdash\) Goals formula. The formula is written as D, S \(\vdash\) R or S, K \(\vdash\) R. The ideas however are the same. The next chapter will explain how our terminology relate to the original papers.

The characterization of this formula as the “E = mc² of requirements engineering” is due to Anthony Hall who co-developed the REVEAL requirements engineering method based this formula with colleagues at Praxis Critical Systems (Hall 2010; Hammond, Rawlings, and Hall 2001).

The Four-Variable Model of systems engineering originates from the work of David Parnas and Jan Madey on how to document requirements for control systems, notably for aircraft and nuclear power plants (Parnas and Madey 1995). That work shares many ideas with Zave and Jackson’s theory.

2.7 Review Questions

To check and deepen your understanding, try to apply the concepts in this chapter to the ambulance dispatching system introduced in Chapter 1.

Question 2.1 Phenomena

Which of the following phrases describe phenomena of the ambulance dispatching system? Remember that a phenomenon is an observable state or event.

1. An incident occurs at 10 Downing Street.
2. A person calls the emergency service to report the incident.
3. An ambulance arrives at 10 Downing Street.
4. An ambulance.
5. The ambulance response time must be less than 14 minutes.

Show Solution

• The first three phrases describe phenomena; all three are observable events.
• The fourth is not a phenomena. An ambulance is neither a state nor an event. An ambulance is an entity. Entities are things with persistent identities. Phenomena are about entities, but the entities themselves are not phenomena. We talk more about entities in Chapter 17 on conceptual models.
• The fifth phrase is also not a phenomena. It is a statement of need about the relation between two phenomena: the ambulance arrival at the incident (phenomena A) must occur less than 14 minutes after the reporting of the incident (phenomena B).

Question 2.2 Classify Phenomena

The Machine is the Computer Aided Dispatch (CAD) software. The CAD receives inputs from call handlers who encode details about each emergency calls from the public. It also receives ambulance location information from the Global Positioning System (GPS) and information about ambulance status from the Mobile Data Terminals (MDT) on board of each ambulance. When an ambulance is allocated to an incident, the CAD sends a mobilisation order to the ambulance’s Mobile Data Terminal.

Classify each of the following phenomena as either:

• W: World Phenomena, not shared with Machine
• I: Machine input
• O: Machine output
• M: Machine phenomena, not shared with the World

1. An incident occurs at 10 Downing Street.
2. A person calls the emergency service to report the incident.
3. A call handler encodes the incident details into the CAD.
4. Ambulance with ID 123 is at Buckingham Palace.
5. Ambulance with ID 123 is available.
6. The function findNearestAvailableAmbulance() returns the ambulance ID 123.
7. The CAD sends mobilisation instructions to ambulance 123’s Mobile Data Terminal.
8. The ambulance crew for ambulance 123 accept the mobilisation on the Mobile Data Terminal.
9. The ambulance with ID 123 arrives at 10 Downing Street.

Show Solution

1. An incident occurs at 10 Downing Street. W
2. A person calls the emergency service to report the incident. W
3. A call handler encodes the incident details into the CAD. I
4. Ambulance with ID 123 is at Buckingham Palace. W
5. Ambulance with ID 123 is available. W
6. The function findNearestAvailableAmbulance() returns the ambulance ID 123. M
7. The CAD sends mobilisation instructions to ambulance 123’s Mobile Data Terminal. O
8. The ambulance crew for ambulance 123 accept the mobilisation on the Mobile Data Terminal. W
9. The ambulance with ID 123 arrives at 10 Downing Street. W

Caution

One common question is why phenomena 4, 5, 8 and 9 are W and not I.

The answer is that the ambulances’ real location and status are not shared with the CAD.

The phenomena “ambulance 123 is at Buckingham palace” is located in the World and not at the interface with the CAD. The CAD has not direct access to that phenomena. Instead, the CAD inputs are GPS messages that provide information about ambulance location. The reception of a GPS message saying that “ambulance 123 is at Buckingham palace” and whether ambulance 123 is actually at Buckingham palace are two different phenomena. Seeing these phenomena as different is useful because it helps us realise that the information the CAD receives about ambulances’ locations might sometimes be inaccurate.

The same applies for the ambulance status: the actual status of an ambulance and the status information that the CAD receives from the Mobile Data Terminal are different phenomena. It is important to see them as separate because the status information received by the CAD could sometimes be inaccurate.

Machine inputs and outputs are World phenomena that are directly shared with the Machine. They must be really happening at the interface of the Machine with the World, not some distance away from that interface.

Hall, Anthony. 2010. “E = mc\(^{2}\) Explained.” In Software Requirements and Design: The Work of Michael Jackson, edited by Bashar Nuseibeh and Pamela Zave. Good Friends Publishing Company.

Hammond, Jonathan, Rosamund Rawlings, and Anthony Hall. 2001. “Will It Work?” In Proceedings Fifth IEEE International Symposium on Requirements Engineering, 102–9. IEEE.

Jackson, Michael. 1995a. Software Requirements & Specifications: A Lexicon of Practice, Principles and Prejudices. ACM Press/Addison-Wesley Publishing Co.

———. 1995b. “The World and the Machine.” In 17th International Conference on Software Engineering (ICSE’95).

Jackson, Michael, and Pamela Zave. 1995. “Deriving Specifications from Requirements: An Example.” In 17th International Conference on Software Engineering (ICSE’95).

Parnas, David Lorge, and Jan Madey. 1995. “Functional Documents for Computer Systems.” Science of Computer Programming 25 (1): 41–61.

Zave, Pamela, and Michael Jackson. 1997. “Four Dark Corners of Requirements Engineering.” ACM Transactions on Software Engineering and Methodology (TOSEM) 6 (1): 1–30.