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 computer-
based 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 830-

1993

 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
 Optional part for specifying of the hardware that the software system is
to expected control

 Detailed software specification

 Detailed description of the expected system functionality

 Reliability and performance requirements

 Describes the reliability and performance expected.

 Appendices for
 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 Item Database

User database Item availability

[Library User] Library card

Return Date Issued item [Library User]
[Issue clerk] Issue library
[Library User] Requested Item item

Activity diagram for library system.

33
Example – cont’d

Update details
User database Item database

User detail
Item
Library Card User status availability
Check user

Requested item Item status

Check item

Checked item
Return date 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
checked issued
Library presented item item item Library
Check Issue
user user

reserve item remove item

reserved items removed items

reserved item

Release
released item

Data flow process from the domain of the issue desk

36
Example – a VOSE state transition
Off-desk
remove

check loan
Presented Checked On-loan

reserve
release
Reserved
State transition diagram seen by the issue desk

use return present

On-loan Finished On-shelf 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 3. Determines the item price and adds the
each item. 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 5. Calculates and presents the sale total.
Cashier indicates to the POST that item
entry is completed.

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 9. Shows the balance due back to the
amount. Customer. Generate a receipt.
10. The Cashier deposits the cash 11. Logs the completed sale. The Cashier
received and extracts the balance owing. 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