Requirements and Design
When writing requirements it is very easy to end up producing a design rather than specifying what is wanted. IEEE 830 the IEEE Recommended Practice of Software Requirements Specifications (SRS) has a sentence in “4.7 Embedding Design in the SRS” which states:
“A requirement specifies an externally visible function or attribute of a system”.
This sentence allows us to define the important differences between what should be included in the Business Case, requirements documents, and design documents.
Business Case and Requirements
If a requirement has to be externally visible then it eliminates including aims, objectives or aspirations in the requirements documents. The appropriate place to include these is as part of the Business Case where the risks and opportunities for a new system are described.
The requirements documents can then be verified against the Business Case to see if the specified requirements are consistent with what it is hoped the system will achieve.
The notorious phrase “The system will be user friendly” can be seen to be an aspiration for the system and therefore part of the Business Case, and not the requirements documents. The requirements might then specify externally visible criteria such as the font size, font colour, the number of options available on any particular screen, and the logical screen contents, all of which can then be verified to see if they are consistent with the user friendly aspiration.
Testing Requirements
The statement that it must be externally visible also implies that it is possible to test any requirement that is specified. The external visibility does not mean that a function or attribute is only visible as part of the system facilities by being displayed on a screen or printout. Instead it means that it is potentially visible by using special testing rigs or programs to display internal variables or to interrogate a database. A requirement is not a requirement unless it can be tested. And the only things that can be tested are those that are externally visible.
Requirements Documents
A misconception with requirements is that they must avoid doing design. This misunderstanding is between the requirements needing to design the functionality of the system and the design needed to construct it as a software system. The sentence states that requirements specify a “function or attribute of the system”. These by their nature imply a logical design for the system. The Specific Requirements of the SRS has separate sections for each element including:
- External Interfaces - descriptions at a logical level all the interfaces into and out of the system whether from users or other systems. This includes purpose, screen or data formats, allowable ranges of data etc. Everything about the data that comes into and out of the system.
- Functions - What the system will logically do with the data including: validity checks, processing that takes place, what inputs are used and outputs produced, error handling etc.
- Logical Database - The logical requirements for any data that needs to be stored including: the types of information held, entity models and their relationships, etc.
All of these items express in a logical format what the system will do, and should be expressed in enough detail, that they can be worked through by a group of people to simulate what the system will achieve, and therefore allow designers to design, and testers to test a system.
Design Documents
What is not included in the requirements documents is the design of the physical aspects of how the system will be built as a computer system. This includes how the functions will be split between various code modules, the interfaces between the modules, and the physical data base structures. The design documents are about how the system will be built, not how it will work. It is similar to the difference between an architect’s drawing showing how a building will be laid out in terms of rooms, thus representing the requirements, and the construction engineers drawing showing how the building will be constructed representing the design.
Summary
The separation of responsibilities between various types of documents can be summarised as:
- Business Case - amongst other things deals with the overall scope and aspirations for the proposed system.
- Requirements documents - deal with the logical input, output, functions and data models to meet the scope and aspirations of the Business Case.
- Design documents - deal with how the logical requirements will be physically constructed in the system.
This structured approach to responsibilities means that the users will concentrate on what they need, and the developers on providing that functionality.
Requirement Issues
- User Requirements - three areas to include and one to avoid when writing them.
- Characteristics of Good Requirements - eight characteristics and where they fit into communication, control and construction.