Requirements documents should have a common structure which should be defined as a company standard and should be checked as part of the document quality assurance process. A standard document structure should encapsulate what your organisation thinks is the best way to organise a requirements document. Because of the diversity of different types of system which may be developed, you may need to have variants from a single standard depending on the type of system and the expected readership of the document.
| Key benefit | Higher-quality, lower-cost requirements documents |
| Costs of introduction | Moderate -high |
| Costs of implementation | Low |
| Guideline type | Basic |
If a standard is to be useful, it must reflect the best practice in your organisation for requirements documents. You should examine the structure of several existing requirements documents to find common characteristics. You should also discuss, with document users, what they like and dislike about these existing documents and what they think have been omitted from these documents.
The best document structure for your needs depends on custom and practice in your organisation, the type of system being developed and the organisational system development processes. We canÕt tell you the best structure for you but, in developing a structure, you may find it helpful to use some published standard as a starting point.
A number of different large organisations such as the US Department of Defense and the IEEE have defined their own standard for requirements documents. Probably the most accessible of these standards is the IEEE/ANSI 830-1993 standard which suggests the following structure for requirements documents:
1. Introduction
2. General description
3. Specific requirements covering functional, non-functional and interface requirements. These should document external interfaces, functionality, performance requirements, logical database requirements, design constraints, system attributes and quality characteristics.
Appendices
Index
This is a generic document structure and organisations should adapt it to their own specific needs. Irrespective of its organisation, the standard should define the information which you would expect to find in a requirements document. This may include:
1. An overview of the system and the benefits of developing the system.
2. A glossary explaining the technical terms used.
3. A definition of the services or functional requirements of the system.
4. A definition of system properties or non-functional requirements such as reliability, safety, etc.
5. Constraints on the operation of the system and the system development process.
6. A definition of the systemÕs operating environment and likely changes to that environment.
7. Detailed system specifications expressed as system models (see Chapter 7) showing the relationships between system components. These may include data processing models, data structure models, etc. You should only include them if you need to produce a very detailed requirements document.
A requirements document standard must allow for differences between systems. You should be able to omit parts of the document and to add new sections. Part of your standard should therefore be an introductory page which explains allowed variances from the defined standard.
To allow for variants, you may find it helpful to define the standard as a list of stable and variant parts. Stable parts are those chapters (such as an introduction and a glossary) which should appear in all requirements documents. Variant parts are those chapters which may but need not be included and whose contents may vary depending on the system being specified.
If organisations do not already have a standard, we recommend that this should be one of the first guidelines implemented. Of course, as good practices are introduced, the standard may have to be revised to take account of the organisationÕs increasing level of requirements engineering process maturity.
An extensive summary of requirements standards is given in Standards, Guidelines and Examples on System and Software Requirements Engineering (M. Dorfman and R. H. Thayer, IEEE Press, 1990).
Setting up any kind of standard is not cheap. It may take several months of effort to analyse and understand the existing documents and to extract an appropriate standard from them. In large organisations especially, you must also allow for a long period of consultation before the standard can be agreed. Once a standard has been established, it should be reviewed periodically and updated when necessary. This is relatively inexpensive assuming that the standard does not have to be radically changed.
Once you have established a standard and requirements engineers have become familiar with it, the costs of actually applying the standard are low. You need some quality checks to assure conformance but apart from that, using the standard should not significantly increase the costs of producing a requirements document.
Some people, particularly software developers, are sometimes resistant to standards. They argue against a standard on the grounds that it will reduce the flexibility and, potentially, increase the costs of producing the requirements document. Apart from the fact that this is a pretty dubious argument, you should always remember, however, that the document is likely to be read more often than it is written. Any increased costs in writing the document are likely to be offset by lower costs in document reading.