Requirement Document: Why? What? How?

Requirements Specifications

Why we -need to write specifications

·         Purpose and audience

·         Choosing an appropriate size and formality

·         Desiderata for Specifications

·         Properties of good specifications

·         Typical problems What not to include

Structure of a requirements document
IEEE standard

Requirements vs. Specifications Application Domain Machine Domain

D - domain properties

R - requirements

C – computers

P - programs

I wish these drug inventory figures were up to date!

When a stock delivery list is received, the system shall add the item counts to the current inventory levels.

When a prescription is filled the system shall…

Deliveries and prescriptions are the only way the stock levels change

R:

D:

S: P:

C:

Software Requirements Specification

Baseline for evaluating the software

·         supports testing, V&V

·         “enough information to verify whether delivered system meets requirements”

·         Baseline for change control

Audience

·         Customers & Users

·         interested in system requirements…

·         …but not detailed software requirements

·         Systems (Requirements) Analysts

·         Write other specifications that interrelate

·         Developers, Programmers

·         Have to implement the requirements

·         Testers

·         Have to check that the requirements have been met

·         Project Managers

·         Have to measure and control the project

How do we communicate the Requirements to others?

It is common practice to capture them in an SRS. But an SRS doesn’t need to be a single paper document...

Appropriate Specification

Consider two different projects:

a.       Tiny project
1 programmer, 2 months work programmer talks to customer, then writes up a 2-page memo

b.       Large project
 50 programmers, 2 years work team of analysts model the requirements, then document them in a 500-page SRS

Purpose o f specification

·         Crystalizes programmer’s understanding

·         Feedback to customer

·         Build-to document

·         Must contain enough detail for all the programmers

M a n a g e m e n t v i e w

·         Spec is irrelevant; have already allocated resources

·         Will use the spec to estimate resource needs and plan the development

Readers

Primary: Spec author;
Secondary: Customer

Primary: programmers, testers, managers;
Secondary: customers

A complication: Procurement

·         An ‘SRS’ may be written by the procurer:

·         SRS is really a call for proposals

·         Must be general enough to yield a good selection of bids…and specific enough to exclude unreasonable bids the bidders:

·         SRS is a proposal to implement a system to meet the CfP must be specific enough to demonstrate feasibility and technical competence and general enough to avoid over-commitment the selected developer:

·         Reflects the developer’s understanding of the customer’s needs forms the basis for evaluation of contractual performance or by an independent RE contractor!

·         Choice over what point to compete the contract

Early (conceptual stage)

·         can only evaluate bids on apparent competence & ability

Late (detailed specification stage)

·         more work for procurer;

·         appropriate RE expertise may not be available in-house

IEEE Standard recommends SRS jointly developed by procurer & developer

Desiderata for Specifications

Valid (or “correct”)

 Expresses the real needs of the stakeholders (customers, users,…)

 Does not contain anything that is n o t “required”

Unambiguous

 Every statement can be read in exactly one way

Complete

 All the things the system must do…

 …and all the things it must not do!

 Conceptual Completeness

 E.g. responses to all classes of input

 Structural  Completeness

 E.g. no TBDs!!!

Understandable (Clear)

 E.g. by non-computer specialists

Consistent

 Doesn’t contradict itself

 Uses all terms consistently

Ranked

 Indicates relative importance / stability of each requirement

Verifiable

 A process exists to test satisfaction of each requirement

There is no Perfect SRS!

incomplete incomplete

not understandable not understandable

ambiguous ambiguous

redundant redundant inconsistent inconsistent

add explanations

resolve

reduce

expand expand condense

formalize

…etc!

University of Toronto Department of Computer Science

© 2004-5 Steve Easterbrook. This presentation is available free for non-commercial use with attribution under a creative commons license. 8

Use Appropriate Notations

Natural Language?

“The system shall report to the operator all faults that originate in critical functions or that occur during execution of a critical sequence and for which there is no fault recovery response.” ( t h i s i s a d a pt e d f r o m a r e a l N A S A s pe c f o r t h e i n t e r n a t i o n a l s pa ce s t a t i o n )

Or a decision table?

Originate in critical functions? F T F T F T F T

Occur during critical sequence? F F T T F F T T

No fault recovery response? F F F F T T T T

Report to operator?

SRS Contents

Software Requirements Specification should address:

Functionality.

 What is the software supposed to do?

External interfaces.

 How does the software interact with people, the system's hardware, other hardware, and other software?
What assumptions can be made about these external entities?

Required Performance.

 What is the speed, availability, response time, recovery time of various software functions, and so on?

Quality Attributes.

 What are the portability, correctness, maintainability, security, and other considerations?

Design constraints imposed on an implementation.

 Are there any required standards in effect, implementation language, policies for database integrity, resource limits, operating environment(s) and so on?

University of Toronto Department of Computer Science

© 2004-5 Steve Easterbrook. This presentation is available free for non-commercial use with attribution under a creative commons license. 10

SRS should not include…

Project development plans

E.g. cost, staffing, schedules, methods, tools, etc

 Lifetime of SRS is until the software is made obsolete

 Lifetime of development plans is much shorter

Product assurance plans

Configuration Management, Verification & Validation, test plans, Quality Assurance, etc

 Different audiences

 Different lifetimes

Designs

Requirements and designs have different audiences

Analysis and design are different areas of expertise

 I.e. requirements analysts shouldn’t do design!

 Ex ce pt w h e r e a ppli ca t i o n d o m a i n co n s t r a i n s t h e d e s i g n

 e.g. limited communication between different subsystems for security reasons. Source: Adapted from Davis, 1990, p183

Typical mistakes

Noise

text that carries no relevant information to any feature of the problem.

Silence

a feature that is not covered by any text.

Over-specification

text that describes a detailed design decision, rather than the problem.

Contradiction

text that defines a single feature in a number of incompatible ways.

Ambiguity

text that can be interpreted in at least two different ways.

Forward reference

text that refers to a terms or features yet to be defined.

Wishful thinking

text that defines a feature that cannot possibly be verified.

Requirements on users

Cannot require users to do certain things, can only assume that they will

Jigsaw puzzles

distributing key information across a document and then cross-referencing

Duckspeak requirements

Requirements that are only there to conform to standards

Unnecessary invention of terminology

E.g. ‘user input presentation function’

Inconsistent terminology

Inventing and then changing terminology

Putting the onus on the developers

i.e. making the reader work hard to decipher the intent

Writing for the hostile reader

There are fewer of these than friendly readers

Organizing the Requirements

Need a logical organization for the document
Example Structures - organize by…
External stimulus or external situation e.g., for an aircraft landing system, each different type of landing situation: wind gusts, no fuel, short runway, etc

System feature
e.g., for a telephone system: call forwarding, call blocking, conference call, etc

System response
 e.g., for a payroll system: generate pay-cheques, report costs, print tax info;

External object
 e.g. for a library information system, organize by book type

User type
e.g. for a project support system: manager, technical staff, administrator, etc.

Mode
 e.g. for word processor: page layout mode, outline mode, text editing mode, etc

Subsystem
 e.g. for spacecraft: command&control, data handling, comms, instruments, etc.

IEEE Standard for SRS

·         Introduction Purpose Scope Definitions, acronyms, abbreviations Reference documents Overview

·         Overall Description Product perspective Product functions User characteristics Constraints Assumptions and Dependencies

·         Specific Requirements Appendices Index

·         Identifies the product, & application domain

·         Describes contents and structure of the remainder of the SRS

·         Describes all external interfaces: system, user, hardware, software; also operations and site adaptation, and hardware constraints

Summary of major functions, e.g. use cases

Anything that will limit the developer’s options (e.g. regulations, reliability, criticality, hardware limitations, parallelism, etc)

Summary

Requirements Specs have several purposes:

·         Communication

·         Contractual

·         Basis for Verification

·         Basis for Change Control

Requirements Specs have several audiences:

·         Technical and non-technical

·         Good Specs are hard to write

·         Complete, consistent, valid, unambiguous, verifiable, modifiable, traceable…

·         Project needs vary

·         The amount of effort put into getting the spec right should depend on the possible consequences of requirements errors