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 : External object template

Technical Purpose of Requirements Spec’s Communicates an understanding of the requirements explains both the application domain and the system to be developed Contractual May be legally binding! Expresses an agreement and a commitment Baseline for evaluating subsequent products supports system testing, verification and validation activities should contain enough information to verify whether the delivered system meets requirements Baseline for change control requirements change, software evolves

Audiences for Requirement Spec’s Procurement, users, stakeholders, salespersons Most interested in system requirements Not often interested in detailed software requirements Systems analysts Write various specifications that interrelate Developers, programmers Implementers of the requirements Quality Assurance, validation team Determine that the requirements have been met Project Managers Control the analysis and development processes

Who writes the requirement spec? You - the procurer the Req. Spec becomes a call for bids and proposals Thus must be general enough to enable people to bid but specific enough to do the job and exclude unreasonable bids The marketplace a proposal to implement a system to meet a call for proposals are recieved must be specific enough to demonstrate capabilities and technical competence but they tend to be general enough to avoid over- commitment

Who writes the requirement spec? The winner – i.e. the selected developer will reflect the developer’s understanding of the customers needs will form the basis for evaluation of contractual performance must be checked very rigorously preferably 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 early then can only evaluate bids on apparent competence & ability against a concept you have not tested If done late with a detailed specification then lots of work for you need to be very sure indeed of what you want what you want may not be available in the market the 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 Completeness think about all inputs and outputs – have they been accounted for Structural Completeness ensure 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 yourself Uses all terms consistently Note that inconsistency is hard to detect especially over timescales, system performance and legal requirements Clarity Every statement must only be interpretable in exactly one way Clearly define confusing or specialist terms try to make it readable to a non-expert

How to think about the content for the Spec 3 Quality Assurance and validation Ensure a process exists to test satisfaction of each requirement think about user behaviours and ensure tests exist that reflect these Modifiable Can be changed without difficulty Good structure and cross-referencing It must be kept up to date!

Do not include: Money that 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 plans Timescales Design concepts unless the design idea would constrain performance or development keep as separate information document to balance function with design

Common mistakes (1) Chaff text not relevant to a feature of the problem Invisible features desired feature not in the Spec Over-specification describing the solution not the problem Contradiction defining a feature or need in several contradictory ways

Common mistakes (2) Jigsaw puzzle referring to a term or feature that has yet to be defined in the text distributing key information all over the place ”Would be nice if” asking for things you cannot possibly validate Invented terminology optical digital rendering device Defensive writing write for the positive reader not the hostile ones!

The IEEE specification