6,,2 • User requirements 127
4.5 LIBSYS shall provide a financial accounting system that maintains records of all payments made by users of the system. System managers may configure this system so that regular users may receive discounted rates.
User requirements
The user requirements for a system should describe the functional and non-functional requirements so that they are understandable by system users without detailed technical knowledge. They should only specify the external behaviour of the sys-tem and should avoid, as far as possible, syssys-tem design characteristics.
Consequently, if you are writing user requirements, you should not use software jargon, structured notations or formal notations, or describe the requirement by describ-ing the :,ystem implementation. You should write user requirements in simple lan-guage, with simple tables and forms and intuitive diagrams.
How,~ver, various problems can arise when requirements are written in natural
languag'~ sentences in a text document:
1. Lack of clarity It is sometimes difficult to use language in a precise and unam-biguous way without making the document wordy and difficult to read.
2. Requirements confusion Functional requirements, non-functional requirements, sysicem goals and design infonnation may not be clearly distinguished.
3. Requirements amalgamation Several different requirements may be expressed together as a single requirement.
As an illustration of some of these problems, consider one of the requirements for the library shown in Figure 6.8.
This requirement includes both conceptual and detailed information.Itexpresses the concept that there should be an accounting system as an inherent part of LIB-SYS. However, it also includes the detail that the accounting system should sup-port discounts for regular LIBSYS users. This det:lil would have been better left to the system requirements specification.
It is good practice to separate user requirements from more detailed system ments in a requirements document. Otherwise, non-te:chnical readers of the user require-ments may be overwhelmed by details that are really only relevant for technicians.
Figure 6.9 illustrates this confusion. This example is taken from an actual require-ments aocument for a CASE tool for editing software design models. The user may specify that a grid should be displayed so that entities may be accurately positioned in a diagram.
Software requirements
:u
GrIdfldlltla To assist in the positioningof entities on a diagram, theusermay
tum on a grid in either centimetres or inches, via an option on the control panel. Initially, the grid isoff. Thegrid may be tumed on andoffatany time during an editing session and can be toggled between inches and centimetresatany time.Agrid option will be provided on the reduce-to-fit view but the numberof grid lines shownwill be reduced to avoid filling the smaller diagram with grid lines.
The fIrst sentence mixes up three kinds of requirements.
1. A conceptual, functional requirement states that the editing system should pro-vide a grid. It presents a rationale for this.
2. A non-functional requirement giving detailed information about the grid units (centimetres or inches).
3. A non-functional user interface requirement that defmes how the grid is switched on and off by the user.
The requirement in Figure 6.9 also gives some but not all initialisation infor-mation. It defInes that the grid is initially off. However,itdoes not defIne its units when turned on.Itprovides some detailed information-namely, that the user may toggle between units-but not the spacing between grid lines.
User requirements that include too much information constrain the freedom of the system developer to provide innovative solutions to user problems and are dif-fIcult to understand. The user requirement should simply focus on the key facili-ties to be provided. I have rewritten the editor grid requirement (Figure 6.10) to focus only on the essential system features.
Whenever possible, you should try to associate a rationale with each user requirement. The rationale should explain why the requirement has been included and is particularly useful when requirements are changed. For example, the ratio-nale in Figure 6.10 recognises that an active grid where positioned objects auto-matically 'snap' to a grid line can be useful. However, this has been deliberately rejected in favour of manual positioning. Ifa change to this is proposed at some later stage, it will be clear that the use of a passive grid was deliberate rather than an implementation decision.
To minimise misunderstandings when writing user requirements, I recommend that you follow some simple guidelines:
I. Invent a standard format and ensure that all requirement defInitions adhere to that format. Standardising the format makes omissions less likely and require-ments easier to check. The format I use shows the initial requirement in bold-face, including a statement of rationale with each user requirement and a reference to the more detailed system requirement specifIcation. You may also
Figure 6.10 Adefinition of an editor grid facility
6.3 Ii System requirements 129
2.6.1 Grid fadlltles
The editor shall provide a pkI fadllty where a
metrtx
of horizontal andvertIuI linesprovidea backpound totheeditor window.This grid shallbea passivegrid where the alignment of entities is the user's responsibility.Rationale:Agrid helps the user to create a tidy diagramwithwel1-spaced entities. Although an active grid, where entities 'snap-to' grid lines canbe useful, the positioning is imprecise. The user iis thebestperson to decide where entities shouldbepo~iitioned.
Specification: ECLIPSE/WS/TooIs/DE:/FSSection5.6 Source: RayWilson, Glasgow Office
include information on who proposed the requirement (the requirement source) so that you know whomtoconsult if the requirement has to be changed.
2. Use language consistently. You should always distinguish between mandatory and desirable requirements.Mandatory requirl~ments are requirements that the system must support and are usually written using 'shall'.Desirable require-ments are not essential and are written using 'should'.
3. Use text highlighting (bold, italic or colour) to pick out key parts of the requirement.
4. Avoid, as far as possible, the use of computer jargon. Inevitably, however, detailed technical tenns will creep into the user requirements.
The Robertsons (Robertson and Robertson, 1999), in their book that covers the VOLERE requirements engineering method, recommend that user requirementsbe initially written on cards, onerequirl~mentper card. They suggest a number of fields on each,~ard,such as the requirements rationale, the dependencies on other require-ments, the source of the requirerequire-ments, supporting materials, and so on. This extends the fonnat that I have used in Figure 6.10, and it can be used for both user and system requirements.
6.3 System requirements
System requirements are expanded versions of the user requirements that are used by software engineers as the starting point for the system design. They add detail and explain how the user requirements shouldbeprovided by the system. They may
130 Chapter 6. Software requirements