Jim Briggs, 26 October 1998

What are requirements?

A confusing example

Picture from p14 of Davis (telephone system in new hotel). Each person is saying something different.

1. General statement of need;
2. 1 is too general - come up with list of features needed;
3. has just been on SADT (Structured Analysis and Design Technique - SofTech) course; believes that if all had been on course, all would be on same wavelength;
4. select from among existing systems the one that optimises price and performance;
5. Let's decide exactly how we want each feature to work, then get vendors to bid on satisfying needs, then select lowest bidder;
6. has just been on PSL/PSA (Problem Statement Language/Problem Statement Analyzer - Meta Systems) course; believes could start storing and analysing all requirements in a requirements database;
7. With experience of similar telephone systems, knows that all PABXs consist of the same five pieces. Why not define inputs, outputs and interfaces to each?
8. Believes that SA (Structured Analysis) is superior to SADT or PSL/PSA.

Requirement: (Collins Pocket English Dictionary) - something required or demanded; something needed, necessity.

When does the requirements phase start? When recognise that problem exists and needs solution. Examples: application oriented (need a new way to do X); business oriented (need X to challenge competitor or meet revenue goals); product improvement oriented (existing X is unreliable). Or, when new software idea arises.

When does the requirements phase finish? When we have complete description of desired external behaviour of system.

Requirements is about what we want, without saying how we will do it. Problem: "what versus how" dilemma: one person's how is another person's what!

All depends on level you choose.

Establishing what services a system should provide is called requirements analysis. Once this has been done, documenting it is called requirements specification.

This is the first step in the traditional software process.

User usually has a "need" at very high level. E.g. "We need a system to do X". Unrealistic to present this to developer and expect him to come up with acceptable system. Needs must be analysed to determine requirements.

Large scale systems are usually "wicked" problems (Rittel and Webber) - no straight-forward answer; no "right" answer. (More on this later.) Any formulation of the problem is bound to be inadequate. System development discovers the problem as well as the solution.

Why? Cannot be definitive about problem specification:

• system usually required in place where no system (or inadequate) system in place - hard to anticipate the effects of new system on organisation;
• large user community has diverse requirements and priorities - final solution is a compromise;
• people who pay for it are not usually the users of it - budgetary and organisational constraints.

Distinction between "goals" and requirements. Goals (such as "user friendly") are not testable as they are subjective. May wish to convert goals to requirements by being more specific: e.g. "all user command selection by menus".

Terminological problems. A "requirements specification" can be anything from a broad outline statement to a mathematical formal specification. See table on p22 of Davis.

Fundamental problem is conflict between need to document system so it can be understood by potential users (readability) with need to produce system specification that can act as basis for contract between user and supplier. Users prefer higher level of abstraction than level of detail required to act as contract.

Therefore important that specifications produced at different levels of abstraction (for different readers) with correlations between levels. We distinguish the following levels:

• Requirements definition: statement in natural language of services the system is expected to provide. Should be understandable by non-specialist (client and contractor management and potential users).
• Requirements specification (aka functional specification): statement in more formal notation of services in more detail. Should be precise enough to act as contract between procurer and developer. Understandable to technical staff from both sides. Degree of formality will depend on background of procurer's technical people.
• Software specification: abstract description of software design intended to serve as basis for design and implementation. Main readers will be software designers rather than users or management. Formal techniques are appropriate.

Roles of "systems analyst" and "software engineer". Systems analyst responsible for analysing existing system and determining relevant information.

Steps in deriving requirements specification:

1. Feasibility study. Are needs satisfiable using currently available technologies? Can proposed system be cost-effective (from business point of view) given budgetary constraints? Really a systems analysis task.
2. Problem analysis. Brainstorming, interviewing users, identifying constraints. Becoming acquainted with problem. Problems: trading off constraints, organising quantities of information.
3. Requirements specification. Set out detailed and precise description of requirements. "Pen in hand". Some high-level design carried out in parallel. Organise ideas, resolve conflicting views, eliminate inconsistencies and ambiguities.

Diagram on p21 of Davis.

Steps not sequential. Errors in requirements definition may be discovered and need modifying.

Why waste time/money worrying about requirements?

Davis' 5 hypotheses:

1. The later in the development life cycle that a software error is detected, the more expensive it is to repair. Figures from GTE, TRW and IBM (mid-70s):

Stage	Relative cost
Requirements	0.1/0.2
Design	0.5
Coding	1
Unit test	2
Acceptance test	5
Maintenance	20

Reason for this? Probably not because coding bugs are inherently more expensive to detect and fix than design bugs, etc. Mizuno's diagram from p25 of Davis. Errors introduced at each stage propagate at lower levels.

2. Many errors remain latent and are not detected until well after the stage at which they are made. TRW figures - 54% of errors detected after unit test.
3. There are many requirements errors being made. Example - an approved US Army MIS had 500 errors in requirements spec. document.
4. Errors made in requirements specifications are typically incorrect facts, omissions, inconsistencies and ambiguities. Example system - 77% of errors were non-clerical.
5. Requirements errors can be detected. Example system - 65% of errors can be detected by inspection.

Taxonomy of applications

Can we classify applications to enable us to choose appropriate techniques for their analysis and specification?

Common properties.

1. Difficulty of problem. Hard (never been solved before) or not-hard (existing known solutions).
2. Relationship in time between data and processing. Static (all data available before program starts processing - most batch systems) or dynamic (data arrives during processing - all interactive systems).
3. Number of simultaneous tasks to be performed. Sequential (one thing at a time) or parallel (multiple tasks simultaneously).
4. Relative difficulty of data, control and algorithmic aspects of problem. Which of these is most difficult to specify: organisation or format of data, or how environment and system control each other (interact - often systems with timing requirements), or transformation of inputs into outputs. Many applications exhibit more than one of these.
5. Deterministic (same answer every time) versus non-deterministic (not predictable - AI systems).

Examples:

Lecture 5 - Requirements and specifications 2

Software requirements document

The SRD (Davis: SRS) is a critical document as it may serve as the basis for a contract between developer and procurer.

Emphasise that it is about what not how. Set out in such a way that the design may be validated against it.

In principle it should be complete and consistent. (Should specify everything and no requirements should conflict.) Should be no misinterpretation. Disagreements between customer and developer should be worked out at the requirements stage, not later. In practice this is difficult, particularly if requirements stated in natural language. Must accept that errors and omissions will exist; therefore document should be amenable to change.

Developer may wish to keep SRD fairly ambiguous in order to provide more flexibility during design. However, SRD should be specific about how system will look externally to its environment (or user). This may limit designs (e.g. by describing a particular user interface) but the SRD author can get around this by stipulating that his "design" is merely an aid to understanding and can be replaced by one that is equivalent. Why not use SRD "design" as real design? - different motives: SRD design is chosen because it is understandable; the real design optimises qualities such as performance, space, reliability and maintainability.

Testing is only possible of requirements that are not ambiguous or inconsistent.

If customer says "I want the software to do X" how do we know whether this is a new requirement or an old one? Read the SRD to find out. If it is new then update SRD, update design, update code. SRD is only definition of what software is supposed to do. Thus control of the contents of the SRD is control of the evolution of the system.

• should only specify external system behaviour;
• should specify constraints on the implementation;
• should be easy to change;
• should serve as reference tool for system maintainers;
• should record forethought about the life-cycle of the system;
• should characterise acceptable responses to undesired events.

The SRD is a reference tool. Should have table of contents, one or more indexes, glossary of terms, list of changes anticipated, etc.

It is likely a combination of the requirements definition and requirements specification talked about before. In practice the definition and specification may sometimes be presented separately (best for users, as details can be ignored) and sometimes as a single document (best for developers since two parts can be kept together).

1. Introduction. Describe need for system and place system in context. Briefly describe functionality and present rationale. How system fits into overall business or strategic objectives.
2. System Model. Relationship between system components and the system and its environment. Appropriate to use graphical descriptions in this section.
3. Functional requirements. Services provided for user. In requirements definition these would normally be described using natural language with cross-references to more detailed specification.
4. Hardware. If to be implemented on special hardware, describe it and interfaces. Alternatively, set out minimal and optimal configurations of off-the-shelf hardware on which the system may execute.
5. Database requirements. Logical organisation of data used by system and its interrelationships.
6. Non-functional requirements. Constraints under which software must operate. Relate to functional requirements.
7. Maintenance information. Fundamental assumptions upon which system is based. Describe anticipated changes due to changing hardware or user needs.
8. Glossary. Define technical terms, principally for non-technical users. Also useful for development staff in defining application terms. Writer should not make assumptions about experience or background of reader.
9. Index. May be desirable to produce more than one index, e.g. index of functions.

Its organisation should follow that of the software system being described. Cross-referenced to requirements definition.

A perfect SRD would be:

1. Correct. Iff every requirement stated therein represents something required of system to be built. If the software must respond to a button press within 5 seconds and the SRD states that "the software shall respond to all button presses within 10 seconds", that requirement is incorrect.
2. Non-ambiguous. Iff every requirement stated therein has only one interpretation. Glossary helps here but not completely. Examples from Davis p185-188.
3. Complete. Four qualities:
1. Everything the software is supposed to do is included in the SRD - not simple to find something that is missing by examining what is present. Tempting to say SRD must state those things that the software must not do - however universe is pretty big!
2. Definitions of responses of the software to all classes of data in all classes of situations are included. Both valid and invalid data. Define output for every input (function of state of system).
3. All pages are numbered; all figures and tables are numbered, named and referenced. All terms and units of measure are provided. Completeness from a word processing perspective.
4. No sections are "to be determined". If necessary, the SRD should say by who and by when (not "tomorrow").
4. Verifiable. Iff every requirement stated therein is verifiable. A requirement is verifiable if there is some finite cost effective process with which a person or machine can check that the system as-built meets it. Verifiability is [importantly] a function of the SRD - not a function of the product. Ambiguity non-verifiability. Cannot test "usually" or "often". Cannot verify "the program shall not enter an infinite loop".
5. Consistent. Iff no subset of requirements conflict. Could be
1. Conflicting terms.
2. Conflicting characteristics. Product must exhibit contradictory traits.
3. Temporal inconsistency. Product must obey contradictory timing characteristics.
6. Understandable by non-computer specialists. Formal notations often make it impossible for non-specialists to understand the SRD.

Format attributes

7. Modifiable. If its structure and style are such that any necessary changes can be made easily, completely and consistently. Can locate a section to be modified if a need changes. (Sometimes improve readability by adding redundancy - repeating things in different places - but this decreases modifiability.) Indexes and cross-reference tables essential.
8. Traceable. If the origin of each of its requirements is clear, and if it facilitates referencing each requirement in future development or enhancement documentation. Four kinds of traceability:
1. Backwards-from-requirements implies that we know why every requirement exists (implies each requirement references its source in other documents).
2. Forward-from-requirements implies that we understand which components of the software satisfy each requirement (demands each requirement in SRD references a component of the design).
3. Backward-to-requirements implies that every software component references those requirements it helps satisfy (implies each requirement has a unique name or reference number).
4. Forward-to-requirements implies that all documents that preceeded the SRD can reference the SRD (also implies names and reference numbers).

(All above references must be explicit.) Traceability gives ability to change requirement if software does not meet it (after reference to reason for requirement).

Requirements traceability matrix (RTM): a row for every requirement, a column for each design component, an X indicates that the design component helps satisfy the requirement. An empty row indicates a requirement not met. An empty column indicates a superfluous design component. RTM reduces effort to locate cause of failures or to analyse adverse effects of a planned change.

9. Annotated. Purpose is to provide guidance to development organisation. Two types common: relative necessity and relative stability. Necessity: essential, desirable, optional. Customer may prefer to have system now without X, rather than in 6 months with X. Tell developers what requirements are worthy of delaying schedule. Stability: stable, volatile. Gives clues where to build in flexibility.

Achieving all the above is impossible. Attempt to eliminate inconsistency and ambiguity (e.g. by reducing natural language) might make it less understandable by non-specialist. Atttempt to achieve completeness may rocket costs and increase size of document.

There is no such thing as a perfect SRD.

Is the SRD always written by the developer? What difference would it make if it were written by the customer?

Competitive bidding scenario. In this case it make as general as possible (to allow ideas you haven't thought of) but specific (to exclude outlandish solutions).

What should not go in a SRD?

Project requirements (e.g. staffing, costs, milestones, phases, reporting procedures). These have different lifespans. SRD has same lifespan as code. Project requirements are only of concern during development.

Designs. Partition documentation (milestone to produce each part). Different audiences.

Product assurance plans (e.g. configuration or V&V plans). Same reasons as above.