Documenting Requirements

Requirements specification
• The process of writing down the user and system
requirements in a requirements document.
• User requirements have to be understandable by end-
users and customers who do not have a technical
background.
• System requirements are more detailed requirements and
may include more technical information.
• The requirements may be part of a contract for the system
development
– It is therefore important that these are as complete as
possible.
The software requirements document
• The software requirements document is the
official statement of what is required of the
system developers.
• Should include both a definition of user
requirements and a specification of the system
requirements.
• It is NOT a design document. As far as
possible, it should set of WHAT the system
should do rather than HOW it should do it.
Agile methods and requirements
• Many agile methods argue that producing a requirements
document is a waste of time as requirements change so
quickly.
• The document is therefore always out of date.
• Methods such as XP use incremental requirements
engineering and express requirements as ‘user stories’.
• This is practical for business systems but problematic for
systems that require a lot of pre-delivery analysis (e.g.
critical systems) or systems developed by several teams.
Users of a requirements document
Requirements document variability
• Information in requirements document depends on type of
system and the approach to development used.
• Systems developed incrementally will, typically, have less
detail in the requirements document.
• Requirements documents standards have been designed e.g.
IEEE standard. These are mostly applicable to the
requirements for large systems engineering projects.
Ways of writing a system requirements
specification
Notation Description
Natural language The requirements are written using numbered sentences in natural language.
Each sentence should express one requirement.

Structured natural The requirements are written in natural language on a standard form or
language template. Each field provides information about an aspect of the
requirement.
Graphical notations Graphical models, supplemented by text annotations, are used to define the
functional requirements for the system; UML use case and sequence
diagrams are commonly used.
Mathematical These notations are based on mathematical concepts such as finite-state
specifications machines or sets. Although these unambiguous specifications can reduce
the ambiguity in a requirements document, most customers don’t understand
a formal specification. They cannot check that it represents what they want
and are reluctant to accept it as a system contract
 Natural language specification
• Requirements are written as natural language
sentences supplemented by diagrams and
tables.
• Used for writing requirements because it is
expressive and universal. This means that the
requirements can be understood by users and
customers.
Example requirements for the insulin
pump software system

3.2 The system shall measure the blood sugar and deliver
insulin, if required, every 10 minutes. (Changes in blood sugar
are relatively slow so more frequent measurement is
unnecessary; less frequent measurement could lead to
unnecessarily high sugar levels.)

3.6 The system shall run a self-test routine every minute with
the conditions to be tested and the associated actions defined
in Table 1. (A self-test routine can discover hardware and
software problems and alert the user to the fact the normal
operation may be impossible.)
Functional requirements for the MHC-
PMS
 A user shall be able to search the
appointments lists for all clinics.
 The system shall generate each day, for
each clinic, a list of patients who are
expected to attend appointments that day.
 Each staff member using the system shall
be uniquely identified by his or her 8-digit
employee number.
 Requirements imprecision
 Problems arise when requirements are not precisely
stated.
 Ambiguous requirements may be interpreted in
different ways by developers and users.
 Consider the term ‘search’ in requirement 1
User intention – search for a patient name across
all appointments in all clinics;
Developer interpretation – search for a patient
name in an individual clinic. User chooses clinic
then search.
 The Language of Requirements
• The use of consistent language makes it easier to identify
different kinds of requirements.
• A simple example of this is the use of “shall” as a key word to
indicate the presence of a requirement in the text.
• Some approaches go so far as to use “shall”, “should” and
“may” to indicate different priorities of requirement.
• stakeholder requirements are primarily concerned with
capability and constraints on capability.
• A capability statement should express a (single) capability
required by one or more identified stakeholder types (or user
groups).
 The Language of Requirements
• A typical capability requirement takes the following form:
The < stakeholder type > shall be able to < capability>.
• Where there are some aspects of performance or constraint
associated solely with the requirement, they may also be stated in
the text, for instance giving the form:
The < stakeholder type > shall be able to < capability >
within < performance > of < event >
while < operational condition>.
• The weapons operator shall be able to fire a missile within 3
seconds of radar sighting while in severe sea conditions.
• The < system > shall < function > <object > every < performance >
<units>.
• The coffee machine shall produce a hot drink every 10 seconds.
Problems with natural language
• Lack of clarity
– it is sometimes difficult to use language in a
precise and unambiguous way, without making the
document wordy and difficult to read
• Requirements confusion
– Functional, non-functional requirements and
design information tend to be mixed-up.
• Requirements amalgamation
– Several different requirements may be expressed
together in a single requirement.
 Using Attributes for requirements
• A simple textual statement is not sufficient fully to define a requirement;
there is other classification and status information that each requirement
carries.
• Rather than clutter the text of a requirement, additional information should
be placed in “attributes” attached to the requirement.
• Attributes allow the information associated with a single requirement to be
structured for ease of processing, filtering, sorting, etc.
• [SH234] The ambulance control system shall be able to handle up to 100
simultaneous emergency calls.
– Source: R. Thomas
– Priority: Mandatory
– Release: 1
– Review status: Accepted
– Verifiable: Yes
– Verification: by system test.
Categories of attributes
 Structured specifications
• An approach to writing requirements
where the freedom of the requirements
writer is limited and requirements are
written in a standard way.
• This works well for some types of
requirements
– e.g. requirements for embedded control
system but is sometimes too rigid for writing
business system requirements.
 Form-based specifications
• Definition of the function.
• Description of inputs and where they come
from.
• Description of outputs and where they go
to.
• Description of the action to be taken.
• Pre and post conditions (if appropriate).
• The side effects (if any) of the function.
 Form based specification
Req ID Title

Priority Critical, Standard, or Optional

Inputs

Preconditions

Requirement
statements

Output

Postcondition
s
 FR 1 Placing a meal order
Priority Critical

Preconditions The pattern shall be logged into the system

inputs Meal date, delivery time, delivery location, food item description, food item quantity,

Requirements 1.1-The COS shall prompt the Patron for the meal date
statements
1.2 -If the meal date is the current date and the current time is after the order cutoff time, the COS shall inform
the patron that it’s too late to place an order for today. The Patron can either change the meal date or cancel
the order.
1.3-The COS shall display a menu for the date that the Patron specified.
1.4-The menu for the specified date shall display only those food items for which at least one unit is available in
the cafeteria’s inventory and which may be delivered.
1.5-When the Patron indicates that he does not wish to order any more food items, the COS shall display the
food items ordered, the individual food item prices, and the payment amount calculated per BR-12.
1.6-The COS shall prompt the Patron to confirm the meal order.
The Patron can confirm, edit, or cancel the order.
1.7-The COS shall let the Patron order additional meals for the same or for a different date. BR-3 and BR-4
pertain to multiple meals in a single order.
1.8-When the Patron indicates that he is done placing orders, the COS shall ask the user to select a payment
method.
1.9.1-If the meal is to be picked up in the cafeteria, the Patron shall choose to pay by payroll deduction or by
cash at the time of pickup.
1.9.2-If the Patron selected payroll deduction, the COS shall issue a payment request to the Payroll System.
1.10If the payment request is accepted, the COS shall display a message confirming acceptance of the order
with a transaction number.
1.11 If the payment request is rejected, the COS shall display the reason for the rejection. The Patron shall
either cancel the order, or change the payment method to cash and request to pick up the order at the
cafeteria.
Output Meal order detail, meal order number, transaction ID

Postconditions 1- The Inventory system successfully deducted the meal quantity

2- The payroll system successfully registered the transaction
3-The meal order is successfully saved in the database
 A structured specification of a
requirement for an insulin pump
 A structured specification of a
requirement for an insulin pump
Hierarchical textual tags
User Interfaces in SRS
 Criteria for Writing Requirements Statements
--Individual

• There are certain criteria that every statement of

requirement should meet.
• Atomic: each statement carries a single traceable
element.
• Feasible: technically possible within cost and schedule.
• Legal: legally possible.
• Abstract: does not impose a solution
 Criteria for Writing Requirements Statements
--Individual

• Unambiguous: An requirement is unambiguous if, and only if,

requirement stated therein has only one interpretation.
– “A user shall be able to search the appointments lists for all
clinics.”
– “Aircraft that are nonfriendly and have an unknown
mission or the potential to enter restricted airspace within
5 minutes shall raise an alert”
• Combination of “and” and “or” make this an ambiguous
requirement
• In cases where a term used in a particular context could have
multiple meanings, the term should be included in a glossary
where its meaning is made more specific.
 Criteria for Writing Requirements Statements
--Individual

• Verifiable: A requirement is verifiable if and only if

there exists some finite cost effective process with
which a person or machine can check that the actual
as-built software product meets the requirement
• Each statement must be verifiable, and it is known
how.
– Non-verifiable requirements include statements
such as “works well”, “good human interface”, and
shall “usually happen”.
Criteria for Writing Requirements Statements—Set of
requirements

• In addition, there are other criteria that apply to the set of

requirements as a whole:
• Complete: An SRS is complete if, and only if, it includes the
following elements:
• All significant requirements, whether relating to functionality
or constraints.
• Definition of the responses of the software to all realizable
classes of input data in all realizable classes of situations.
– Note that it is important to specify the responses to both valid and
invalid input values.
• Full labels and references to all figures, tables, and diagrams
in the SRS and definition of all terms and units of measure.
 Criteria for Writing Requirements Statements—Set of
requirements
• Consistent: no two requirements are in conflict.
• The specified characteristics of real-world objects may conflict.
– the format of an output report may be described in one
requirement as tabular but in another as textual.
• There may be logical or temporal conflict between two specified
actions. For example,
– One requirement may specify that the program will add two inputs
and another may specify that the program will multiply them.
(logical)
– One requirement may state that A must always follow B, while
another may require that A and B occur simultaneously. (temporal)
• Two or more requirements may describe the same real-world object
but use different terms for that object.
– For example, a program request for a user input may be called a
prompt in one requirement and a cue in another. The use of
standard terminology and definitions promotes consistency.
 Criteria for Writing Requirements
Statements—Set of requirements
• Non-redundant: each requirement is
expressed once.
• Modular: requirements statements that
belong together are close to one another.
• Structured: there is a clear structure to the
requirements document.
 Summary:
Guidelines for writing requirements
• Invent a standard format and use it for all
requirements.(single sentence!!)
• Use language in a consistent way. Use shall for
mandatory requirements, should for desirable
requirements.
• Use text highlighting to identify key parts of the
requirement.
• Avoid the use of computer jargon (specialised
words).
• Include an explanation (rationale) of why a
requirement is necessary.