Requirements Documentation
Download
Report
Transcript Requirements Documentation
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