Requirements Documentation

Reza Sherafat
CAS 703 Software Design Seminar
February 2005

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)

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.

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%.

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

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 contd

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

R2

R3

R4

R5

R6

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 contd

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 contd

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 contd
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

Checked

loan

On-loan

reserve
release

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 contd

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 didnt 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