Writing Requirements

Steven J Zeil:

Last modified: Dec 21, 2019
Contents:

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

1.1 The Primary Requirements Documents

Waterfall processes often distinguished between

2 Requirements Definition

2.1 Writing requirements definitions

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:


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.

2.3 Example (Spreadsheet)

A simpler requirements definition.

Read through this.

3 Requirements Specification

The SRS (Software Requirements Specifications) adds detail to the requirements definition.

3.1 Characteristics of a good SRS

An SRS should be

  1. Correct;
  2. Unambiguous;
  3. Complete;
  4. Consistent;
  5. Ranked for importance and/or stability;
  6. Verifiable (see below)
  7. Modifiable;
  8. Traceable (see below)

Most of these are self-explanatory.

3.1.1 Verifiability

Requirements should be written so that they can be objectively verified


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


Improving Traceability

4 Documenting Individual Requirements

There are many different styles for writing requirements.

The choice often depends on

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, or D.

3.1.2 Each face contains two sensors, named the x and y 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).

4.2 Pre and Post Conditions

A pre-condition is what must be true before a function can be performed.

A post-condition describes what the function will accomplish as a boolean expression that will be true upon completion.

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: RSDIMU

RSDIMU/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 procedure

Outputs: Sensor failure linFail & noise indicators linNoise

Destination: Edge consistency check and acceleration estimation functions

Requires: Instrument

Pre-condition: Sensor is not already marked as failed

Post-condition: linFail[Face,Sensor] and linNoise[Face,Sensor*] will be set to true if std-dev(offraw) > 3 * linstd.

Side effects: Changes to sensor status affect face status as well.


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 Documentation
catalog.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_ */

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:

  1. Validity checks on the inputs
  2. Exact sequence of operations
  3. Responses to abnormal situations, including
    • Overflow
    • Communication facilities
    • Error handling and recovery
  4. Effect of parameters
  5. 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


Non-functional requirements examples

4.5.1 Requirements separation

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


2. Overall Description


4. Appendices

Skipping forward for just a moment,…

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.

"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 )

Choose an organization that divides the requirements up into natural, easily understood groups.


However it is organized, it must eventually describe


All of these organizations observe strict separation of functional and non-functional requirements.

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.

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

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

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

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

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

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.

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.

6.1 Example of Formal Specification

A formal specification of the RSDIMU

 


 

Some schemas from the RSDIMU specification: