The software requirements document (sometimes called the software requirements specification or SRS) is the official statement of what the system developers should implement. It should include both the user requirements for a system and a detailed specification of the system requirements. In some cases, the user and system requirements may be integrated into a single description. In other cases, the user requirements are defined in an introduction to the system requirements specifica-tion.Ifthere are a large number of requirements, the detailed system requirements maybepresented in a separate document.
The requirements document has a diverse set of users, ranging from the senior management of the organisation that is paying for the system to the engineers respon-sible for developing the software. Figure 6.16, taken from my book with Gerald Kotonya on requirements engineering (Kotonya and Sommerville, 1998) illustrates possible users of the document and how they use it.
The diversity of possible users means that the requirements document has to be a compromise between communicating the requirements to customers, defining the requirements in precise detail for developers and testers, and including information about possible system evolution. Information on anticipated changes can help sys-tem designers avoid restrictive design decisions and help syssys-tem maintenance engi-neers who have to adapt the system to new requirements.
The level of detail that you should include in a requirements document depends on the type of system that is being developed and the development process used.
When the system will be developed by an external contractor, critical system spec-ifications need to be precise and very detailed. When there is more flexibility in the requirements and where an in-house, iterative development process is used, the requirements document can be much less detailed and any ambiguities resolved dur-ing development of the system.
A number of large organisations, such as the US Department of Defense and the IEEE, have defined standards for requirements documents. Davis (Davis, 1993) dis-cusses some of these standards and compares their contents. The most widely known
Figure 6.16 Users of a requirements document
I
6.5 II The software requirements document 137
Specify the requirements and System
I
read them to check that they __-'---i~meet their needs. Customers customersI
specify changes to therequirements.
I:
Managersr-
Use the requirements document to plan a bid for the system and to plan the system development process.I
Use the requirements toI
---;~ understand what system is to be developed.
...-'----'---"'L I
Use the requirements to II---i~ develop validation tests forthe system.
...-"
.
System Use the requirements to
maintenance understand the system and engineers the relationships between its
parts.
standard is IEEE/ANSI 830-1998 (IEEE, 1998). This IEEE standard suggests the following structure for requiremems documents:
I. Introduction
1.1 Purpose of the requiremt:nts document 1.2 Scope of the product
1.3 Definitions, acronyms and abbreviations 1.4 References
1.5 Overview of the remainder of the document 2. General description
3. Specific requirements cover functional, non··functional and interface require-ments. This is obviously the most substantial part of the document but because
Software requirements
of the wide variability in organisational practice, it is not appropriate to define a standard structure for this section. The requirements may document external interfaces, describe system functionality and performance, specify logical database requirements, design constraints, emergent system properties and quality characteristics.
4. Appendices 5. Index
Although the IEEE standard is not ideal, it contains a great deal of good advice on how to write requirements and how to avoid problems. It is too general to be an organisational standard in its own right. It is a general framework that can be tailored and adapted to define a standard geared to the needs of a particular organ-isation. Figure 6.17 illustrates a possible organisation for a requirements document that is based on the IEEE standard. However, I have extended this to include infor-mation about predicted system evolution. This was first proposed by Heninger (Heninger, 1980) and, as I have discussed, helps the maintainers of the system and may allow designers to include support for future system features.
Ofcourse, the information that is included in a requirements document must depend on the type of software being developed and the approach to development that is used.Ifan evolutionary approach is adopted for a software product (say), the require-ments document will leave out many of detailed chapters suggested above. The focus willbeon defining the user requirements and high-level, non-functional system require-ments. In this case, the designers and programmers use their judgement to decide how to meet the outline user requirements for the system.
By contrast, when the software is part of a large system engineering project that includes interacting hardware and software systems, it is often essential to define the requirements to a fine level of detail. This means that the requirements docu-ments are likely to be very long and should include most if not all of the chapters shown in Figure 6.17. For long documents, it is particularly important to include a comprehensive table of contents and document index so that readers can find the information that they need.
Requirements documents are essential when an outside contractor is developing the software system. However, agile development methods argue that requirements change so rapidly that a requirements document is out of date as soon as it is writ-ten, so the effort that is largely wasted. Rather than a formal document, approaches such as extreme programming (Beck, 1999) propose that user requirements should be collected incrementally and written on cards. The user then prioritises require-ments for implementation in the next increment of the system.
For business systems where requirements are unstable, I think that this approach is a good one. However, I would argue that it is still useful to write a short sup-porting document that defines the business and dependability requirements for the system. Itis easy to forget the requirements that apply to the system as a whole when focusing on the functional requirements for the next system release.
6.5 The software requirements document 139
This should define the expec:ted readership of the document and describe its version history, including a rationale for the creation of a new version and a summary of the changes made in each version.
This should describe theneE~d for the system. It should briefly describe its functions and explain how it will work with other systems. It~;hould describe how the systemfitsinto the overall busi ness or strategic ,objectivesofthe organisation commission1ing the software.
This should define the technical terms used in the document You should not make assumptions about the experience or expertise of the reader.
The service!; provided forthE~ user and the non-functional system requirements should be described in this section. This description may use natural language, diagrams or other notations that are understandable by customers. Product and proces!; standards which must be followed should be specified.
This chapter should present a high-level overview of the anticipated system architecture showing the distribution of functions ac:ross system modules. Architectural components that are reused should be highlighted.
This should describe the funlctional and non-functional requirements in more detail. If necessary, further detail may also bl! added to the Mn-functional requirements, e.g. interfaces to other systems may be defined.
This should set out one or more system models showing the relationships between the system components and the system anditsenvironment These might be object models, data-flow models and semanticdatamodels.
This should describe the fundamental assumptions on which the system is based and anticipated changes due to hardware evolution, changing user needs, etc.
These should provide detailed, specific information which is related tCI the application which is being developed.
Examples o·f appendices that maybeinclUded are hardware and database descriptions. Hardware requirements define the minimal and optimal configurations for the system. Database requirements define the logical organisation of the data used by the system and the relaticmships between data.
several indElxes to the document may be included. As well as a nonmal alphabeticindeJ~there may be an indexof diagrams, aln index of functiclIls, etc.
140 Chapter 6 • Software requirements
KEY POINTS
Requirements for a software system set out what the system should do and define constraints on its operation and implementation.
Functional requirements are statements of the services that the system must provide or are descriptions of how some computations must be carried out. Domain requirements are functional requirements that are derived from characteristics of the application domain.
Non-functional requirements constrain the system being developed and the development process that should be used. They may be product requirements, organisational
requirements or external requirements. They often relate to the emergent properties of the system and therefore apply to the system as a whole.
User requirements are intended for use by people involved in using and procuring the system. They should be written using in natural language, with tables and diagrams that are easily understood.
System requirements are intended to communicate, in a precise way, the functions that the system must provide. To reduce ambiguity, they may be written in a structured form of natural language supplemented by tables and system models.
The software requirements document is the agreed statement of the system requirements.
It should be organised so that both system customers and software developers can use it.
The IEEE standard for requirements documents is a useful starting point for more specific requirements specification standards.
FURTHER READING
4>_i_1 11 _
S{tware Requirements, 2nd ed. This book, designed for writers and users of requirements, discusses good requirements engineering practice. (K. M. Weigers,2003,Microsoft Press.) Mastering the Requirements Process. A well-written, easy-to-read book that is based on a particular method (VOLERE) but which also includes lots of good general advice about requirements engineering. (S. Robertson and J. Robertson, 1999, Addison-Wesley.) Requirements Engineering: Processes and Techniques.This book covers all aspects of the requirements engineering process and discusses specific requirements specification techniques.
(G. Kotonya and I. Sommerville, 1999, John Wiley&Sons.)
Software Requirements Engineering. This collection of papers on requirements engineering includes several relevant articles such as 'Recommended Practice for Software Requirements Specification', a discussion of the IEEE standard for requirements documents. (R. H. Thayer and M.
Dorfman (eds.), 1997, IEEE Computer Society Press.)
EXERCISES
Chapter 6 • Exercises 141
_._---6.1 Identify and briefly describe four types of requirements that may be defined for a computer·
based sllstem
6.2 Discuss the problems of using natural language for defining user and system requirements, and show, using small examples, how structl,ring natural language into forms can help avoid some of these difficulties.
6.3 Discover ambiguities or omissions in the following statement of requirements for part of a ticket·issuing system.
An automated ticket·issuing system sells rail tickets. Users select their destination and input a credit card and a personal identification number. The rail tiicket is issued and their credit card accountchan~ed. When the user presses. the start button, a menu display of potential destinatllons is activated, along with a message to the user to select a destination. Once a destinatiion has bE!en selected, users are reqllested to input their credit card. Its validity is checked and the Lser is thE!I1 requested to input a personal identifier. When the credit transaction hasbE~en validated, the ticket is issued.
6.4 Rewrite the above description llsing the structured approach described in this chapter.
Resolve the identified ambiguities in some appropriate way.
6.5 Draw a sequence diagram showing the actions performed in the ticket·issuing system. You may make any reasonable assumptions about the system. Pay particular attention to specifying user errors.
6.6 Using the technique suggested here, where naturallanguagE~ is presented in a standard way, write plausibleuSI~rrequirements for the following functions:
• The cash·dispensing function in a bank ATM
• Thespelling·chl~ck and correcting function in a word processor
• An unattended petrol (gas) pump system tl1at includes a credit card reader. The customer swipes the card through the reader andthl~n specifies the amount of fuel required. The fuel is deliverecl and the customer s account debited.
6.7 Describe four types of non·functional requirements that may be placed on a system. Give examples of each of these Itypes of requiremE'nt.
6.8 Write a set of non-functional requirements fOl' the ticket·issuing system, setting out its expected reliability and its response time.
6.9 Suggest how an engineer responsible for drawing up a system requirements specification might keep track of the relationships between functional and non·functional requirements.
6.10 You have taken aiob with a software user who has contractE!d your previous employer to develop a system for them. You discover that your company's interpretation of the requirements is different from the interpretation taken by your previous employer. Discuss what you should do in such a situation. You know that the costs to your current employer will increase if the ambiguities are not resolved. You have also a responsibility of confidentiality to your previOUS employer.