Requirements
Documentation
Reza Sherafat
CAS 703 – Software Design Seminar
February 2005
1
Content
 Introduction
 Requirements Engineering Process
 Requirements Documentation Templates
 Viewpoint-oriented Requirement Documentation
methods
 Object-oriented approach
 Common Problems
2
Problems in developing computer
based systems since 1960s
 Too many systems are late or over budget
 Systems don't do what the users really want or
never used to the effectiveness
(there are rarely a single reason for these problems
but a major contributory factor is difficulties with
system requirements)
3
What are requirements?
 A specification of what should be implemented
 Defined at early stages of a system development
 Include:
 how the system should behave
 application domain information
 constraints on the system's operation
 specification of a system property or attribute.
4
What is requirements engineering?
 A relatively new term invented to cover all of the
activities involved in discovering, documenting and
maintaining a set of requirements for a computerbased system.
 Use of the term 'engineering' implies that
systematic and repeatable techniques should be
used to ensure that system requirements are
complete, consistent and relevant.
5
How much does requirements
engineering cost?
 Depends on the type and size of the system being
developed
 In a survey for large hardware/software systems,
about 15% of the total budget is taken up by the
requirements engineering activities. For smaller
projects it is about 10%.
6
Common requirements' problems
 Don't reflect the real needs of the customers
 Inconsistent and incomplete
 Expensive to make changes to the requirements
after they have been agreed
 Misunderstandings between customers, those
developing the system requirements and software
engineers
7
What happens when requirements
are wrong?
 System may be delivered late or with more cost than
originally expected
 Customer and end-user might not be satisfied with
the system
 System may be unreliable in use, with regular system
crashes happening all the time.
 If system continues in use, the costs of maintaining
and evolving are usually very high.
8
What is a requirements engineering
process?
 Requirements engineering process is a structured set
of activities which are followed to derive, validate and
maintain a systems requirements document. The
activities include:
 Requirements elicitation
 Requirements analysis and negotiation
 Requirements documentation
 Requirements validation
9
Requirements elicitation techniques
 The system requirements are discovered through
consultation with stakeholders, from system
documents, domain knowledge
 Other names are 'requirement acquisition' or
'requirement discovery'
10
Interviews
 Closed loop: interviewer looks for answers to a set
of pre-defined questions
 Open loop: there are no pre-defined agenda and
discussion is done in an open-ended way.
11
Scenarios

Stories of how the system will be used

End-users and other stakeholders find it easier to relate to real-life
examples rather than abstract descriptions of functions of a
system

They should at least include:

Description of the state of the system before entering the scenario

Normal flow of events in the scenario

Exceptions to the normal flow of events

Information about other activities which might be going at the same
time

Description of the state of the system after the scenario
12
An example scenario

Scenario of ordering a report from a library:

The user logs on the system

The order document is issued

The reference number of the document is entered

A delivery option is selected

The user logs out.

Exception: if the reference number is incorrect, the user is
offered to enter the document reference or invoke the system
help.
13
Requirements Reuse

A good practice to reuse as much knowledge as possible when
developing a new system

Although requirements for each system is distinct, there are a
number of situations where reuse is possible:

Where requirement is concerned with providing information
about the application domain, e.g. constraints on the
system.

Where the requirement is concerned with the style of
presentation of the information, like the user interface of
the whole systems for an organization.

Where the requirements reflect company policies such as
security requirements.
14
Prototyping
 An initial version of the system which is available
early in the development process
 Helps elicit and validate the system requirements
 'throw-away' prototypes used to help elicit and
analyze the requirements are often called
 In contrast evolutionary prototypes are intended to
deliver a workable system quickly to the customer
15
Prototyping – cont’d
 Prototypes help to establish the overall feasibility
and usefulness of the system
 The only effective way of developing system user
interface.
 May be possible to be used in system tests later in
the validation process
16
Requirements analysis and
negotiation
 Aim at discovering problems with the system
requirements and reach agreement on changes to
satisfy all system stakeholders
 Requirements are analyzed in detail
 Different stakeholders negotiate to decide on which
requirements are to be accepted
 Since there are inevitably conflicts between the
requirements from different sources, information may
be incomplete or may be incompatible with the budget
available
17
Analysis checklists

A list of questions which the analyst may use to assess the
requirement. Some items in these lists may be:

Premature design

Combined requirements

Unnecessary requirements

Use of non-standard software/hardware

Requirements ambiguity

Conformance with business rules

Requirements testability

Requirements realism
18
Interaction matrices
 Used to discover the interactions between
requirements and to highlight requirements
conflicts and overlaps
 If we can not assume that conflicts do not exist, we
should assume that there is a potential conflict
 Undetected conflicts are much more expensive to
resolve
19
Example – Interaction matrices
O: OVERLAP
C: CONFLICT
Requirement
R1
R2
R3
R4
R5
R6
R1
-
-
O
-
C
C
R2
-
-
-
-
-
-
R3
O
-
-
O
-
O
R4
-
-
O
-
C
C
R5
C
-
-
C
-
-
R6
C
-
O
C
-
-
20
Requirements negotiation

Discussing conflicts and finding some compromise which all
of the stakeholders can live with

Meetings are most effective way. Meetings should be
conducted in three stages:

An information stage, explaining the nature of the problem

A discussion stage, in which stakeholders discuss possible
solutions

A resolution stage, where actions concerning the requirements
are agreed
21
Requirements Documentation
 There are many different ways to structure the
requirements documents, depending on:
 The type of the system being developed
 The level of detail included
 Organizational practice
 Budget
 Schedule
22
Standard Templates

Ensures that all the essential information is included

A number of different large organizations such as the US Department
of Defense and IEEE have defined standards for requirements
documents

Probably the most acceptable of these standards is the IEEE/ANSI 8301993

The standard recognizes differences between systems, and allows for
some variations in the structure.

There is a list of stable and variant parts:

Stable parts

Variant parts
23
IEEE/ANSI 830 - 1993


Introduction:

Purpose of the requirements document

Scope of product

Definitions, acronyms and abbreviations

References

Overview of the remainder of the document
General Description:

Product perspective

Product functions

User characteristics

General constraints

Assumptions and dependencies
24
IEEE/ANSI 830 – 1993 – cont’d
 Specific requirements
 Covering functional, non-functional and interface
requirements. These should include external
interfaces, functionality, performance requirements,
logical requirements, design constraints, system
attributes and quality characteristics
 Appendices
 Index
25
A template based on IEEE/ANSI
830 – 1993

Preface

Introduction
 Definition of the product, its expected usage and an
overview of its functionality

Glossary
 Definition of technical terms and abbreviations used

General user requirements
 The systems requirements from the perspective of the user

System architecture
 A high-level overview of the anticipated system
architecture, showing the distribution of functions across
system modules
26
Example – cont’d

Hardware specification


Detailed software specification


Describes the reliability and performance expected.
Appendices for






Detailed description of the expected system functionality
Reliability and performance requirements


Optional part for specifying of the hardware that the software system is
to expected control
Hardware interface specification
Software components
Data structures specification
Data-flow models of the software system
Detailed object models of the software system
Index
27
Requirements validation


The process outputs are as follows:

A list of problems

Agreed solution
Techniques for requirements validation:

Requirements reviews: Involves a group of people who read
and analyze the requirements

Pre-review checking: one person carries out a quick standards
check to ensure that the documents structure is consistent
with defined standards

Review team membership: Stakeholders from different
disciplines should be involved
28
User manual development


User manual development:

Rewriting the requirements in a different way is a very effective validation
technique.

To rewrite the document you must understand the requirements and the
relationships.

Developing this understanding reveals conflicts omissions and
inconsistencies.
A user manual should include the following information:

A description of the functionality and how to access the functionality through
the user interface

A description of how to recover from difficulties

Installation instructions for users
29
Actors in requirements engineering
process

Domain expert: provide information about the application
domain and the specific problem in that domain which is to be
solved

System end-user: will use the system after delivery

Requirements engineer: eliciting and specifying the
requirements

Software engineer: responsible for developing the software
system

Project manager: planning and estimating the prototyping
project
30
Structured Analysis and Design
Technique (SADT)
 Developed in the late 1970s by Ross
 Based on data-flow models that view the system as a
set of interacting activities
 Decomposes the problem into a set of hierarchical
diagram, each composed of a set of boxes and arrows
 Each lower level is documented separately and
represents the refinement to the previous level
 The most abstract level is the 'context diagram',
representing the system's activities with a set of
input/outputs.
31
SADT viewpoints
 SADT does not have an explicit notion of
viewpoints, viewpoints are an intuitive extension
Control
Input
ACTIVITY
Output
Mechanism
32
Example
User database
User database
[Library User]
[Issue clerk]
Item Database
Item availability
Library card
Return Date
[Library User] Requested
Item
Issue library
item
Issued item
[Library User]
Activity diagram for library system.
33
Example – cont’d
User database
Item database
Update details
User detail
Library Card
Check user
Requested item
User status
Item
availability
Check item
Checked item
Return date
Item status
Issue item
Issued item
Refinement of the issue library item function
34
Viewpoint-oriented System
Engineering (VOSE)
 Developed in Imperial College London in early
1960s
 VOSE is a framework that addresses the entire
system development cycle
 Uses data-flow and state transition scheme to
model the system world
 Requires further examination of consistency
between different viewpoints
35
Example – a VOSE data flow
Library
user
presented item
Check
reserve item
reserved items
checked
item
Issue
issued
item
Library
user
remove item
removed items
reserved item
released item
Release
Data flow process from the domain of the issue desk
36
Example – a VOSE state transition
Off-desk
remove
check
Presented
release
Checked
loan
On-loan
reserve
Reserved
State transition diagram seen by the issue desk
On-loan
use
Finished
return
On-shelf
present
Presented
State transition diagram seen by the library user
37
Use cases
 Used in OO Analysis
 Definition

Describes the sequence of events of some types of users
(actors) using some part of system functionality to
complete a process
 Actors: A person, organization or external system
playing a role in some interactions with the system
 Associations: interactions between actors and use cases
38
Use cases – example
Actor action
System response
1. This use case begins when a Customer
arrives at a POST checkout with items to
purchase.
2. The Cashier records the identifier from
each item.
3. Determines the item price and adds the
item information to the running sales
transaction.
If there is more than one same item, the
Cashier can enter the quantity as well.
The description and price of the current
item are presented.
4. On completion of the item entry, the
Cashier indicates to the POST that item
entry is completed.
5. Calculates and presents the sale total.
Alternative Courses
_ Line 2: Invalid identifier entered. Indicate error.
39
Use cases – example – cont’d
6. The Cashier tells the Customer the
total.
7. The Customer gives a cash payment,
possibly greater than the sale total.
8. The Cashier records the cash received
amount.
9. Shows the balance due back to the
Customer. Generate a receipt.
10. The Cashier deposits the cash
received and extracts the balance owing.
11. Logs the completed sale. The Cashier
gives the balance owing and the printed
receipt to the Customer.
12. The Customer leaves with the items
purchased.
Alternative Courses
_ Line 7: Customer didn’t have enough cash. Cancel sales
transaction
40
Use Cases Diagrams in UML
 Use cases – horizontal ellipses
 Actors – stick figures
 Associations – lines (the arrowhead indicates the
direction of initial invocation)
 System boundary box (optional)
41
A simple use case diagram
42
Common problems in writing
requirements
 Requirements are written in complex conditional
clauses which are confusing
 Terminology is used in a sloppy and inconsistent
way
 The writers of the requirement assume that the
reader has specific knowledge of the domain of the
system and may leave out some essential
information
43
Things that the writer should bear
in mind
 Requirements are read more often than they are
written. Invest more effort to write documents that
are easy to read and understand
 Readers of requirements come from diverse
backgrounds. Don't assume that readers have the
same background and knowledge as you
 Writing clearly and concisely is not easy. Allow
sufficient time for drafting and reviewing
44
Guidelines
 Define standard templates for describing
requirements
 Use language simply, concisely and consistently. Use
short sentences and paragraphs
 Use diagrams appropriately to present overviews and
relationships between entities
 Specify requirements quantitatively (number of users,
response time requirements, etc.)
45
Questions
 Q1 – Identify 10 functional system requirements
for an online university library system.
 Q2 – Write use cases for the library system in Q1
and draw the use case diagrams.
 Q3 – Draw state transition and data-flow diagrams
for the library system.
46
References

Bahati Sanga, Assessing and improving the quality of software
requirements specification documents, McMaster University, 2003

G. Kotonya, Requirements Engineering, processes and techniques,
Wiley, 1997

R.S. Pressman, Software Engineering, a practitioner's approach,
Fifth edition, McGraw-Hill

D.M. Berry, Users manuals as a requirements specification, 2003

Zhiming Liu, Object-Oriented Software Development with
UML, The United Nations University, July 2002

How to Draw UML 2 Use Case Diagrams, by Scott W. Ambler,
available online at
http://www.agilemodeling.com/artifacts/useCaseDiagram.htm
47