Writing requirements specifications

Why we need requirements specifications

To give structure to your desires

To avoid waste of resources

To avoid slippage and project creep

Reality check

Is the basis of an agreement to provide a specific service within a budget and time frame

Because you can’t trust anyone

not even yourself!

IEEE Std 830-1998: External object template

Technical Purpose of Requirements Spec’s

Communicates an understanding of the requirementsexplains both the application domain and the system to be developed

ContractualMay be legally binding!

Expresses an agreement and a commitment

Baseline for evaluating subsequent productssupports system testing, verification and validation activities

should contain enough information to verify whether the delivered system meets requirements

Baseline for change controlrequirements change, software evolves

Audiences for Requirement Spec’s

Procurement, users, stakeholders, salespersonsMost interested in system requirementsNot often interested in detailed software requirements

Systems analystsWrite various specifications that interrelate

Developers, programmersImplementers of the requirements

Quality Assurance, validation teamDetermine that the requirements have been met

Project ManagersControl the analysis and development processes

Who writes the requirement spec?

You - the procurerthe Req. Spec becomes a call for bids and proposalsThus must be general enough to enable people to bid but specific enough to do the job and exclude unreasonable bids

The marketplacea proposal to implement a system to meet a call for proposals are recievedmust be specific enough to demonstrate capabilities and technical competencebut they tend to be general enough to avoid over-commitment

Who writes the requirement spec?

The winner – i.e. the selected developerwill reflect the developer’s understanding of the customers needswill form the basis for evaluation of contractual performancemust be checked very rigorouslypreferably by an expert independent of either party

Timing the competition

With all these possible contributors then a choice over when to offer a chance to compete for the work must be made. There are pro’s and con’s to this:

If done earlythen can only evaluate bids on apparent competence & ability against a concept you have not tested

If done late with a detailed specificationthen lots of work for youneed to be very sure indeed of what you wantwhat you want may not be available in the marketthe appropriate analysis and Req Spec writing skills may not be available in-house.

How to think about the content for the Spec 1

Express the real needs of the stakeholders

Specify all the things the system must do

Specify all the things it must not do!

Conceptual Completenessthink about all inputs and outputs – have they been accounted for

Structural Completenessensure there are no “to be decided” for the system structure – must be architecturally complete

Necessity – ensure everything requested is necessary

How to think about the content for the Spec 2

Be consistent and ensure you don’t contradict yourselfUses all terms consistentlyNote that inconsistency is hard to detect especially over timescales, system performance and legal requirementsClarity

Every statement must only be interpretable in exactly one wayClearly define confusing or specialist termstry to make it readable to a non-expert

How to think about the content for the Spec 3

Quality Assurance and validationEnsure a process exists to test satisfaction of each requirementthink about user behaviours and ensure tests exist that reflect these

ModifiableCan be changed without difficultyGood structure and cross-referencingIt must be kept up to date!

Do not include:

Moneythat is part of the tender process and should be kept separate from the Req. Spec.Call for Proposals or Invitation to Tenders can state these instead

Management or project plansTimescalesDesign concepts

unless the design idea would constrain performance or developmentkeep as separate information document to balance function with design

Common mistakes (1)

Chafftext not relevant to a feature of the problem

Invisible featuresdesired feature not in the Spec

Over-specificationdescribing the solution not the problem

Contradictiondefining a feature or need in several contradictory ways

Common mistakes (2)

Jigsaw puzzlereferring to a term or feature that has yet to be defined in the textdistributing key information all over the place

”Would be nice if”asking for things you cannot possibly validate

Invented terminologyoptical digital rendering device

Defensive writingwrite for the positive reader not the hostile ones!

The IEEE specification