Writing Requirements
Steven J Zeil:
Abstract
Requirements documents are written in many different forms. We will look the components common to many of these, with particular attention to the distinction between functional requirements and nonfunctional requirements.
We will look, in detail, at a standard format for Software Requirements Specification (SRS) documents from the IEEE, and we will look more briefly at some alternatives.
1 A “Classical” Approach to Requirements
Problems of requirements analysis
- Stakeholders don’t know what they really want
- Stakeholders express requirements in their own terms (conflicting with developers’ familiar terminology)
- Different stakeholders may have conflicting requirements
- Organizational and political factors may influence the system requirements
- The requirements may change during the analysis process.
- New stakeholders may emerge
1.1 The Primary Requirements Documents
Waterfall processes often distinguished between
-
Requirements definitions: Customer-oriented descriptions of the system’s functions and constraints on its operation
-
Requirements specifications: Precise and detailed descriptions of the system’s functionality and constraints.
2 Requirements Definition
- Should specify external behaviour of the system
- Includes functional and non-functional requirements
-
Functional requirements are statements of the services that the system should provide
- Basically, what outputs should be produced for a given class of inputs
-
Non-functional requirements are constraints on the services and functions offered by the system
- Anything that isn’t “what outputs should be produced for a given class of inputs”
-
2.1 Writing requirements definitions
- Commonly in natural language, supplemented by diagrams and tables
Can lead to problems with
- Lack of clarity.
- Requirements confusion (mixing functional and non-functional reqts)
- Requirements amalgamation: mixing requirments together
2.2 Example (RSDIMU)
Some years ago, I worked on a series of research projects that made use of a Requirements Definition written by a NASA contractor, Charles Rivers Analytics. An updated copy of that document can be found here.
It describes a Redundant Strapped-Down Inertial Measurement Unit, a device that forms part of an aircraft’s navigation system. It uses a bank of accelerometers (sensors that can measure acceleration along a straight line) to determine, at any moment in time, how much and in what direction the aircraft is accelerating.
Integrated over time, the acceleration can yield the history of velocity changes by the aircraft. Integrated again, one can estimate how far and in what direction the aircraft has traveled.
Physically, the RSDIMU consists of a square-based pyramid with the triangular faces being equilateral triangles (a semi-octahedron).
On each triangular face are mounted two sensors, at right angles to each other.
That gives a total of 8 sensors, all at varying angles to one another. That’s more than enough to determine the acceleration of the aircraft in 3 dimensions.
This redundancy (the “R” in RSDIMU) is important because:
-
Over time, some sensors may fail,
- Redundancy means the system continues to function even after multiple failures.
-
Like all physical measurement devices, the sensors are noisy – there are random errors in any real measurement process.
- Redundancy allows us to “average” together the readings to get a more accurate estimate.
From the RSDIMU Requirements Definition:
An RSDIMU consists of a skewed array of redundant inertial sensors and exemplifies the current trend for designing hardware fault tolerant inertial measurement units (IMU’s) for high reliability applications. The portion of the RSDIMU you will handle contains eight linear accelerometers mounted on the four triangular faces of a semioctahedron.
Your procedure will have two functions, both of which are a consequence of the redundancy in the sensor complement of the RSDIMU. The first function is to perform a consistency check to detect and isolate failed sensors. The second is to use the sensors found to be good by the first check to provide estimates of the vehicle’s linear acceleration expressed as components along the north, east, and down axes of a navigational frame of reference.
⋮
an RSDIMU as described here would operate as follows. With the vehicle stationary, as series of sensor readings would be taken over time, and this would comprise the calibration data set for that particular flight. During flight, the sensors would be read periodically at regular time intervals to provide input for the navigation software.
Critique
The preceding requirements mix up functional and non-functional requirements and are incomplete.
- Easy to criticise but hard to write good requirements definitions
- Use of a standard format with pre-defined fields to be filled means that information is less likely to be omitted
2.3 Example (Spreadsheet)
A simpler requirements definition.
Read through this.
- Is it enough for you to understand what the project is?
- Could you see people using this as a basis for deciding whether or not to move forward with a project?
- Can you see any gaps and possible ambiguities that would need to be tightened up before developers understood exactly what they were supposed to produce?
3 Requirements Specification
The SRS (Software Requirements Specifications) adds detail to the requirements definition.
- It should be consistent with the RD.
- Often presented with system models which are developed during the requirements analysis.
- Usually written in natural language but this can be problematical
3.1 Characteristics of a good SRS
An SRS should be
- Correct;
- Unambiguous;
- Complete;
- Consistent;
- Ranked for importance and/or stability;
- Verifiable (see below)
- Modifiable;
- Traceable (see below)
Most of these are self-explanatory.
3.1.1 Verifiability
Requirements should be written so that they can be objectively verified
- Requires precision in terminology
-
This is not good:
The system should be easy to use by experienced controllers and should be organized in such a way that user errors are minimized.
-
The error rate should be been quantified
Experienced controllers should be able to use all the system functions after a total of two hours training. After this training, the average number of errors made by experienced users should not exceed two per day.
-
Making the Subjective Objective
Some possible objective measures of properties that we often consider to be subjective:
Property | Measure |
---|---|
(subjective) | (objective) |
Speed | processed transactions / sec. |
Response time | |
screen refresh time | |
Size | k bytes |
Ease of use | training time |
number of help frames | |
Reliability | mean time to failure |
probability of unavailability | |
failure rate | |
Robustness | time to restart after failure |
probability of data corruption after failure | |
Portability | % of target dependent statements |
number of target systems |
3.1.2 Requirements traceability
Requirements traceability means that related requirements are linked in some way and that requirements are (perhaps) linked to their source
- Traceability is a property of a requirements specification which reflects the ease of finding related requirements.
- Some CASE tools provide traceability support facilities. For example, they may be able to find all requirements which use the same terms.
- Test specifications may attempt to trace tests back to reqts,
- thereby demonstrating that each reqt has been tested.
Improving Traceability
- Assign a unique number to all requirements
- Keep individual requirements small. Break up
"23: The system shall do A and B.
into
"23: The system shall do A.
"24: The system shall do B.
so that we can talk about requirements being satisfied or failed on an individual basis.
-
Cross-reference related requirements using this unique number
-
Produce a cross-reference matrix for each requirements document showing related requirements.
4 Documenting Individual Requirements
There are many different styles for writing requirements.
The choice often depends on
-
Local culture – what the developers are familiar with.
-
Overall organization
- Different schemes for organizing the overall SRS lend themselves to different approaches for writing the specific requirements.
4.1 Structured English
Perhaps most common is the use of a mixture of natural language, mathematics, and diagrams, in a detailed numbered list:
3. Physical structure:
The RSDIMU is composed of an instrument and a display. The display is discussed in Section 6.3. This section is devoted to the structure of the instrument package.
3.1 The instrument package is a semi-octahedron (a square-based pyramid) (Figure 1).
3.1.1 It has four non-base faces, named
A
,B
,C
, orD
.3.1.2 Each face contains two sensors, named the
x
andy
sensors.3.1.2.1 Associated with each sensor is a set of misalignment angles. These are specified further in Section 2.3.2.
Rationale: There is an ideal position for each sensor, but the physical mounting may differ slightly.
3.1.2.2 The misalignment angles are assumed to be small enough (less than 5 degrees) for the sine of the angle to be approximately equal to the value of the angle expressed in radians.
3.1.3 The temperature of the face,
temp
, determines the temperatures of the sensors mounted on the face.Rationale: Sensor output varies with temperature (see section 4.6).
-
Each numbered item is a separate functional requirement.
-
These are often described as “The system shall…” statements.
-
As you can see, however, they often (and maybe preferably) refer to previously introduced subsystems.
-
-
Works well when organizing by feature.
4.2 Pre and Post Conditions
A pre-condition is what must be true before a function can be performed.
- Invoking a function despite its pre-condition being false is considered to be illegal and to have unpredictable results.
- Functions are not required to check their pre-conditions — the pre-condition is an obligation on the caller, not on the function being called.
- Nonetheless, many programmers will add code to check pre-conditions (if they can be checked without slowing the function down) as a form of defensive programming.
A post-condition describes what the function will accomplish as a boolean expression that will be true upon completion.
- This represents the actual statement of what we want the function to do.
Both pre-conditions and post-conditions must be boolean statements.
There is a long tradition of documenting both functions (design and implementation) and functionality (requirements) with pre-conditions and post-conditions:
Example 1: Example: RSDIMURSDIMU/Calibration/4.1
Function: Check for Noise
Description: The variance in a number of readings taken from one sensor while the vehicle was at rest are compared to a threshold value. Sensors whose variance exceeds the threshold are marked as failed due to excessive noise.
Inputs: Face, Sensor, raw sensor data collected on ground, noise threshold
Source: raw sensor data
offraw
from external measurement procedureOutputs: Sensor failure
linFail
& noise indicatorslinNoise
Destination: Edge consistency check and acceleration estimation functions
Requires: Instrument
Pre-condition: Sensor is not already marked as failed
Post-condition:
linFail[Face,Sensor]
andlinNoise[Face,Sensor*]
will be set to true ifstd-dev(offraw) > 3 * linstd
.Side effects: Changes to sensor status affect face status as well.
The “Description” here is informal documentation.
The “real” specification is in the pre- and post- conditions and the side-effects.
The term side effect comes from programming where it refers to any effect of a function that cannot be observed by inspection of the return value and output parameters (e.g., changes to global variables).
Although this looks very low-level, the apparent variables and arrays like
linFail
andlinNoise
are actually defined elsewhere as signals that appear as rows of green/red lights on an indicator panel.
Because pre- and post-conditions are booleans, they are often expressed in mathematical or even programming language notation.
Example 2: Pre- and Post-Conditions in API Documentationcatalog.h/* * catalog.h * * Created on: Apr 10, 2017 * Author: zeil */ #ifndef CATALOG_H_ #define CATALOG_H_ #include <string> #include <iostream> #include "book.h" /** * A list of books, identified by Gutenberg ID. */ class Catalog { public: /** * Create a new empty catalog, capable of holding up to * maxCapacity books. * * @param maxCapacity maximum number of books this catalog * can hold. */ Catalog (int maxCapacity = 100); /** * How many books currently in this catalog? * * @return number of books in the catalog. */ int size() const; /** * How many books can this catalog hold? * * @return max capacity of this catalog. */ int capacity() const; /** * Attempt to alter the capacity of this catalog so that * it can hold at least newCapcity books. Existing books * in the catalog are retained. * * @param newCapacity maximum number of books we would like to be able * to store in this catalog. * @post capacity() >= newCapacity */ void reserve (int newCapacity); /** * Add a book to the catalog. If a book with the same ID exists, it is * replaced by b. * * @pre size() < capacity() || contains(b.getID()) * @post contains(b.getID()) && b == get(b.getID()) */ void add (Book b); /** * Check to see if a book is contained in the catalog. * * @param bookID the ID string of a potential book * @returns true iff a book with that ID is in the catalog. */ bool contains(std::string bookID) const; /** * Return the book associated with a given ID. * * @param bookID the ID string of a potential book * @returns The book with that ID in the catalog, or * Book() if the ID is unknown. */ Book get(std::string bookID) const; /** * Return a book based upon ID ordering. * * @param i index of a desired book. * @return the requested book, or Book() if i is illegal. * * @pre 0 <= i && i < size() * @post if i0 <= i1, get(i0).getID() <= get(i1).getID() */ Book get(int i) const; private: ⋮ }; #endif /* CATALOG_H_ */
- The conditions here are documents in the
@pre
and@post
clauses.
- Not surprisingly, this style probably works best if Section 3 is organized by function(ality).
4.3 Functional and Non-Functional Requirements.
Requirements are generally divided into functional and non-functional.
4.4 Functional Requirements
Functional requirements are the ones that say “if the input is … the output will be …”.
These can include statements about:
- Validity checks on the inputs
- Exact sequence of operations
- Responses to abnormal situations, including
- Overflow
- Communication facilities
- Error handling and recovery
- Effect of parameters
- Relationship of outputs to inputs, including
- Input/output sequences
- Formulas for input to output conversion
4.5 Non-functional requirements
Any requirement that isn’t functional, including
- Performance requirements
- Should be stated in measurable terms.
- e.g., “95% of the transactions shall be processed in less than 1 sec.”
rather than,
“An operator shall not have to wait for the transaction to complete.”
- Database reqts
- data entities, integrity constraints, data retention
- Standards compliance
- Software attributes
- Reliability
- Security
- maintainability
- portability
Non-functional requirements examples
-
Product requirement
4.C.8 It shall be possible for all necessary communication between the APSE and the user to be expressed in the standard Ada character set.
- This could be argued to be functional, because it describes input, but because this is given as an over-arching requirements (“all necessary communication”) and references a standard, it can also be regarded as non-functional.
-
Organizational requirement
9.3.2 The system development process and deliverable documents shall conform to the process and deliverables defined in XYZCo-SP-STAN-95.
-
External requirement
7.6.5 The system shall provide facilities that allow any user to check if personal data is maintained on the system. A procedure must be defined and supported in the software that will allow users to inspect personal data and to correct any errors in that data.
4.5.1 Requirements separation
- Functional and non-functional requirements should, in principle, be distinguished in a requirements specification
- However, this can be difficult as requirements may be expressed as whole system requirements rather than constraints on individual functions
- It is sometimes difficult to decide if a requirement is functional or a non-functional
- E.g., requirements for safety are concerned with non-functional properties but may require functions to be added to the system
5 The IEEE standard SRS outline
There are many ways to organize a requirements document, but this has been an industry standard for a long time.
Table of Contents
1. Introduction
1.1 Purpose
1.2 Scope
1.3 Definitions, acronyms, and abbreviations
1.4 References
1.5 Overview
2. Overall description
2.1 Product perspective
2.2 Product functions
2.3 User characteristics
2.4 Constraints
2.5 Assumptions and dependencies
3. Specific requirements
⋮
Appendixes
Index
(Source: IEEE Std 830-1998, Recommended Practice for Software Requirements Specifications, sect 5)
5.1 The Supporting Text
Much of this outline describes descriptive text that will “surround” the real requirements.
1. Introduction
- Purpose: indicate purpose and intended audience
- Scope: identifies software products to be developed, benefits, objectives
- Identify the software products to be produced
- Explain what they will (and will not) do
- Describe the application area, including benefits and objectives
- Definitions, acronyms, and abbreviations;
- References;
- Overview.
- Describe organization of the remainder of the SRS
2. Overall Description
-
Describe the general background affecting the product and its requirements.
-
Product perspective
- related products and systems
- diagram of major components
- architectural constraints (e.g., required interfaces)
- Product functions (functionality)
- major functions to be performed
- User characteristics;
- Constraints;
- regulatory, hardware, required interfaces, audit functions, reliability, safety, security
- Assumptions and dependencies;
- Apportioning of requirements
- What can be deferred to future versions?
4. Appendices
Skipping forward for just a moment,…
- Sample I/O formats
- GUI screens(?)
- Additional background info
5.2 The Actual Requirements
3. Specific Requirements
The is the real heart of the IEEE SRS — this is where we actually put the requirements.
- Everything else is supporting text. It exists only to make section 3 of the SRS easier to read and understand.
"This section of the SRS should contain all of the software requirements to a level of detail sufficient to enable designers to design a system to satisfy those requirements, and testers to test that the system satisfies those requirements.
5.2.1 Choices of Organization
Section 3 can be organized in different ways ( IEEE Std 830-1998, sect 5.3.7 )
- by operating mode
- by user class
- by object/class
- by feature
- by stimulus
- by function hierarchy
Choose an organization that divides the requirements up into natural, easily understood groups.
- Don’t choose to organize by user class, for example, if you have only identified a single class or role for all users of the system.
However it is organized, it must eventually describe
- every input into the system,
- every output from the system,
- all functions performed by the system
All of these organizations observe strict separation of functional and non-functional requirements.
- In fact, the major difference among these organization is how the functional requirements are arranged and grouped.
- The non-functional requirements appear in separate sections after the functional ones, and those sections are pretty similar across all the organizations.
5.2.2 Organizing by Mode
Some systems have distinct modes of operation that server to strictly limit what functions can be performed at any one time.
- Example: The RSDIMU has two distinct modes: a calibration mode when the plane is on the ground, and a navigation mode when the plane is in the air.
Here is the organization of section 3:
3. Specific Requirements
3.1 External Interface Requirements
3.1.1 User Interfaces
3.1.2 Hardware Interfaces
3.1.3 Software Interfaces
3.1.4 Communications Interfaces
3.2 Functional Requirements
3.2.1 Mode 1
3.2.1.1 Functional reqt 1.1
3.2.1.2 Functional reqt 1.2
⋮
3.2.2 Mode 2
3.2.2.1 Functional reqt 2.1
3.2.2.2 Functional reqt 2.2
⋮
⋮
3.3 Performance reqts
3.4 Design constraints
3.5 Software system attributes
3.5 Other Reqts
-
This is supporting text. Refer to the IEEE standard for details.
-
An alternate form ot the organization by mode allows separate supporting text for each distinct mode.
-
-
This is where the functional reqts are stated. This is the core of the SRS.
-
This is where the non-functional reqts are placed.
5.2.3 Organizing by User Class
Some systems have multiple user classes or roles, with very different functionality seen by each role.
This organization is similar to the previous one, replacing modes by user roles
3. Specific Requirements
3.1 External Interface Requirements
3.1.1 User Interfaces
3.1.2 Hardware Interfaces
3.1.3 Software Interfaces
3.1.4 Communications Interfaces
3.2 Functional Requirements
3.2.1 User class 1
3.2.1.1 Functional reqt 1.1
3.2.1.2 Functional reqt 1.2
⋮
3.2.2 User class 2
3.2.2.1 Functional reqt 2.1
3.2.2.2 Functional reqt 2.2
⋮
⋮
3.3 Performance reqts
3.4 Design constraints
3.5 Software system attributes
3.5 Other Reqts
- Both the supporting text and non-functinal reqts areas are unchanged.
5.2.4 Organizing by Stimulus
This organization is used when the most distinctive characterstic of the system is the different kinds of stimuli – external events or inputs – to which the system must respond.
3. Specific Requirements
3.1 External Interface Requirements
3.1.1 User Interfaces
3.1.2 Hardware Interfaces
3.1.3 Software Interfaces
3.1.4 Communications Interfaces
3.2 Functional Requirements
3.2.1 Stimulus 1
3.2.1.1 Functional reqt 1.1
3.2.1.2 Functional reqt 1.2
⋮
3.2.2 Stimulus 2
3.2.2.1 Functional reqt 2.1
3.2.2.2 Functional reqt 2.2
⋮
⋮
3.3 Performance reqts
3.4 Design constraints
3.5 Software system attributes
3.5 Other Reqts
- Both the supporting text and non-functinal reqts areas are unchanged.
5.2.5 Organizing by Object
If you have performed a full object-oriented analysis and formulated domain and analysis models as a collection of interacting objects, you can use your analysis model as the basis for organizing and stating your reqts.
3. Specific Requirements
3.1 External Interface Requirements
3.1.1 User Interfaces
3.1.2 Hardware Interfaces
3.1.3 Software Interfaces
3.1.4 Communications Interfaces
3.2 Specific Requirements
3.2.1 Class/Object 1
3.2.1.1 Attributes
3.2.1.1.1 Attribute 1.1
⋮
3.2.1.2 Functions
3.2.1.2.1 Functional reqt 1.1
3.2.1.2.1 Functional reqt 1.2
⋮
3.2.2 Class/Object 2
3.2.2.1 Attributes
3.2.2.1.1 Attribute 2.1
⋮
3.2.2.2 Functions
3.2.2.2.1 Functional reqt 2.1
3.2.2.2.1 Functional reqt 2.2
⋮
⋮
3.3 Performance reqts
3.4 Design constraints
3.5 Software system attributes
3.5 Other Reqts
-
Both the supporting text and non-functinal reqts areas are unchanged.
-
The division of section 3.2 is very different from what came before, but makes sense from an OOA point of view.
- Notice that attributes are listed separately, but we don’t list functions but instead jump straight into requirements.
- That’s probably because many functional requirements will express a relationship between multiple functions,
- e.g., “The
top()
function of the stack returns the value most recently supplied to apush(...)
”. - Such statements cannot be cleanly divided into separate lists per function.
- e.g., “The
-
I would expect any SRS using this organization to include lots of UML, amounting to the entire analysis model being embedded in the SRS.
-
And presumably, the doman model appeared in the earlier requirements Definition.
-
- Remember that this is requirements, not design.
-
If we organize by object/class, we are talking about classes discovered and documented in the domain model or analysis model.
(You would not choose this organization if you had not started with OOA.)
They are not necessarily classes that will appear in the design or implementation.
- Though, if you are a firm believer in the OO philosophy, you suspect that there in a high probability of them surviving in a closely related form.
-
5.2.6 Organizing by Feature
Features can be any readily observable behavior or functionality.
3. Specific Requirements
3.1 External Interface Requirements
3.1.1 User Interfaces
3.1.2 Hardware Interfaces
3.1.3 Software Interfaces
3.1.4 Communications Interfaces
3.2 System features
3.2.1 System feature 1
3.2.1.1 Introduction/Purpose of feature
3.2.1.2 Stimulus/Response sequence
3.2.1.3 Associated functional requirements
3.2.1.3.1 Functional reqt 1.1
3.2.1.3.1 Functional reqt 1.2
⋮
⋮
3.3 Performance reqts
3.4 Design constraints
3.5 Software system attributes
3.5 Other Reqts
-
This has supporting text for describing each feature, but the core content is still the functional reqts.
-
The reference to “Stimulus/Response” means that we want to document the inputs/events that trigger the use of this feature, and summarize the effects/outputs of the feature.
5.2.7 Organizing by Functional Hierarchy
This organization supports a form of data-flow analysis that was wide-spread in the pre-OOA days.
5.3 Example: Spreadsheet
Here is a complete SRS in the IEEE 830 style.
-
Organized by feature
-
Pick a feature out of section 3 (e.g., “Assignments”).
-
How does this stack up against our desired quality attributes:
- Correct;
- Unambiguous;
- Complete;
- Consistent;
- Ranked for importance and/or stability;
- Verifiable
- Modifiable;
- Traceable
-
6 A Minority View - Formal Requirements
There is always a dedicated group of advocates who maintain that the use of natural language in requirements specifications is a fundamental flaw.
-
They argue for any of several techniques of formal specification.
-
The influence of formal specification languages on conventional practice lies in the concepts of preconditions and postconditions.
6.1 Example of Formal Specification
A formal specification of the RSDIMU
- written in Zed, a formal specification languages that uses schemas to express constraints on named data states.
- A schema
- names a data state,
- lists component data that makes up that state, and then
- lists constraints (boolean conditions) limiting those components
Some schemas from the RSDIMU specification:
-
The first schema says that a “Point” can be described as
- a 3-dimensional vector (defined earlier) and by
- three components, each a real number (
R
)named “x”, “y”, and “z”, and by - a frame of reference (which expresses where the origin of the coordinate system is and how the axes are oriented).
-
It also says that the three real numbers and the vector are closely related – essentially the real components are just a shorthand for the corresponding components of the vector.
-
The second schema says that a “Direction”
- has all the components and constraints of a Point, and
- has an additional constraint that the size of the vector is 1.0