© Colin Potts C1-1

Requirements Documentation

Colin Potts

Georgia Tech

© Colin Potts C1-2

Customer- and developer-oriented documentation

Customer-oriented Developer-oriented

Name Software reqts. spec.Customer spec.Business reqts.

Software reqts. spec.Functional spec.Technical reqts.

Readership Customerrepresentatives

Development team,QA, testers

Purpose Overview offunctionality

Authoritativereference

Terminology Customer’s Customer’s withsome technical

Representation English with someinformal diagrams

Technical Englishwith formal diagrams

© Colin Potts C1-3

Post-requirements traceability

Requirements

Test cases

Implementation

meets

derived from

passes/fails

© Colin Potts C1-4

Pre- and post-requirements traceability

in AIMS

Requirements

Test cases

Implementation

meets

derived from

passes/failsDetailed design

Specification

meets

meets

© Colin Potts C1-5

Traceability (cont).

1.1 The system shall blah, blah...1.2 If the co-worker is blah, blah, thesystem shall inform the user ...1.2.1...

Input:CoWorker record inwhich blah = 1, and...Expected output:blah = 2

if !(fizzwick(cw)) { for (i=0;i=max;i++) update(cw, i); ...else ...

Reqt Test case

Code

....

© Colin Potts C1-6

Documentation standards

Common document standards exist» e.g IEEE 830 (Software Reqts. Specs.)

�

PurposeScopeDefinitionsabbreviationsReferences

Introduction

ProductperspectiveProductfunctionsUsercharacteristicsGeneralconstraintsAssumptionsdependencies

Generaldescription

Functional requirementsPerformancerequirementsDesignconstraintsAttributesExternalinterfacerequirementsOthjerrequirements

Specificrequirements

Supportinginformation

SRS

© Colin Potts C1-7

AIMS Documentation structure

Reqts. definition�

Introduction

Intro

IntroReqt 1...Reqt n

Functional area #1perspective

IntroReqt 1...Reqt n

Functional area #2functions

IntroReqt 1...Reqt n

Functional area #3characteristics

Current reqtsdescription

Future phase reqtsrequirements

Reqts defn

© Colin Potts C1-8

AIMS Documentation structure

Specification & design�

Purpose

Related documents

Introduction

Intro

Component1...

Component n

System decomposition

Subpart 1...

Subpart n

Component1

...

Subpart 1...

Subpart n

Component n

Subsystem decomposition

Spec & design

© Colin Potts C1-9

AIMS Documentation structure

Functional reqts./app. overview/det. design

�

OverviewExporting dataImporting dataDataStat user functionsTransaction definitionsValid transaction typesFile structuresData file issuesExport transaction type Import transaction typeResponse transaction typeInterface communication specLogical comm/inf flow

Functional requirements

Data files/collection processInterface menu

Application overview�

Detailed design

FR/AO/DD

© Colin Potts C1-10

Documentation and models

Models are formal representations (usually graphical) of the HAS or product» e.g. interaction, data flow, entity-

relationship diagrams Should models be produced with or after reqt.

documentation?

Customer-oriented

Developer-oriented

Models

Customer-oriented

Developer-oriented

Models

Option 1

Option 2

© Colin Potts C1-11

Qualities of requirements documents

Customer-oriented» Unambiguous» In customer’s language» Complete with respect to

intent

Developer-oriented» Technically precise» Consistent» Complete specifications» Feasible» Testable

Both» Clear» Unambiguous» Free of “gold plating”

© Colin Potts C1-12

Requirements reviews & inspections

Informal reviews» Purpose: Critique

and improve requirements

» When: Incrementally & throughout

» Who: Interested parties

Formal reviews» Purpose: Approve

requirements and authorize project

» When: When reqts. docs. are complete

» Who: Owner (in SSM terms)

© Colin Potts C1-13

Class exercise: Requirements critique

Take the requirements document Individually read several paragraphs

carefully, looking for ambiguities As a class, discuss:

» general quality» specific issues» recommend reformulation of reqts.

© Colin Potts C1-14

Requirements documentation: how to

find out more

Example standards» Contained in Dorfman & Thayer’s “green”

tutorial– Heavy systems engineering & DOD emphasis– IS organizations will want to water down many

of these guidelines