SEN204-Software Requirements.pdf

4 Requirements engineering Objectives The objective of this chapter is to introduce software requirements and to explain the processes involved in discovering and documenting these requirements. When you have read the chapter, you will: understand the concepts of user and sys...

4 Requirements engineering Objectives The objective of this chapter is to introduce software requirements and to explain the processes involved in discovering and documenting these requirements. When you have read the chapter, you will: understand the concepts of user and system requirements and why these requirements should be written in different ways; understand the differences between functional and non-functional software requirements; understand the main requirements engineering activities of elicitation, analysis, and validation, and the relationships between these activities; understand why requirements management is necessary and how it supports other requirements engineering activities. Contents 4.1 Functional and non-functional requirements 4.2 Requirements engineering processes 4.3 Requirements elicitation 4.4 Requirements specification 4.5 Requirements validation 4.6 Requirements change 102 Chapter 4 Requirements engineering The requirements for a system are the descriptions of the services that a system should provide and the constraints on its operation. These requirements reflect the needs of customers for a system that serves a certain purpose such as controlling a device, placing an order, or finding information. The process of finding out, analyzing, documenting and checking these services and constraints is called requirements engineering (RE). The term requirement is not used consistently in the software industry. In some cases, a requirement is simply a high-level, abstract statement of a service that a system should provide or a constraint on a system. At the other extreme, it is a detailed, formal definition of a system function. Davis (Davis 1993) explains why these differences exist: If a company wishes to let a contract for a large software development project, it must define its needs in a sufficiently abstract way that a solution is not pre- defined. The requirements must be written so that several contractors can bid for the contract, offering, perhaps, different ways of meeting the client organi- zation’s needs. Once a contract has been awarded, the contractor must write a system definition for the client in more detail so that the client understands and can validate what the software will do. Both of these documents may be called the requirements document for the system†. Some of the problems that arise during the requirements engineering process are a result of failing to make a clear separation between these different levels of descrip- tion. I distinguish between them by using the term user requirements to mean the high-level abstract requirements and system requirements to mean the detailed description of what the system should do. User requirements and system require- ments may be defined as follows: 1. User requirements are statements, in a natural language plus diagrams, of what ser- vices the system is expected to provide to system users and the constraints under which it must operate. The user requirements may vary from broad statements of the system features required to detailed, precise descriptions of the system functionality. 2. System requirements are more detailed descriptions of the software system’s functions, services, and operational constraints. The system requirements docu- ment (sometimes called a functional specification) should define exactly what is to be implemented. It may be part of the contract between the system buyer and the software developers. Different kinds of requirement are needed to communicate information about a system to different types of reader. Figure 4.1 illustrates the distinction between user and system requirements. This example from the mental health care patient informa- tion system (Mentcare) shows how a user requirement may be expanded into several system requirements. You can see from Figure 4.1 that the user requirement is quite †Davis, A.M. 1993. Software Requirements: Objects, Functions and States. Englewood Cliffs, NJ: Prentice-Hall.  Chapter 4 Requirements engineering 103 User requirements definition 1. The Mentcare system shall generate monthly management reports showing the cost of drugs prescribed by each clinic during that month. System requirements specification 1.1 On the last working day of each month, a summary of the drugs prescribed, their cost and the prescribing clinics shall be generated. 1.2 The system shall generate the report for printing after 17.30 on the last working day of the month. 1.3 A report shall be created for each clinic and shall list the individual drug names, the total number of prescriptions, the number of doses prescribed and the total cost of the prescribed drugs. 1.4 If drugs are available in different dose units (e.g. 10mg, 20mg, etc.) separate reports shall be created for each dose unit. 1.5 Access to drug cost reports shall be restricted to authorized users as listed on a management access control list. Figure 4.1 User and system requirements general. The system requirements provide more specific information about the ser- vices and functions of the system that is to be implemented. You need to write requirements at different levels of detail because different types of readers use them in different ways. Figure 4.2 shows the types of readers of the user and system requirements. The readers of the user requirements are not usu- ally concerned with how the system will be implemented and may be managers who are not interested in the detailed facilities of the system. The readers of the system requirements need to know more precisely what the system will do because they are concerned with how it will support the business processes or because they are involved in the system implementation. The different types of document readers shown in Figure 4.2 are examples of system stakeholders. As well as users, many other people have some kind of interest in the system. System stakeholders include anyone who is affected by the system in some way and so anyone who has a legitimate interest in it. Stakeholders range from end-users of a system through managers to external stakeholders such as regulators, Client managers System end-users User Client engineers requirements Contractor managers System architects System end-users Figure 4.2 Readers of System Client engineers different types of requirements System architects requirements Software developers specification 104 Chapter 4 Requirements engineering Feasibility studies A feasibility study is a short, focused study that should take place early in the RE process. It should answer three key questions: (1) Does the system contribute to the overall objectives of the organization? (2) Can the system be implemented within schedule and budget using current technology? and (3) Can the system be integrated with other systems that are used? If the answer to any of these questions is no, you should probably not go ahead with the project. http://software-engineering-book.com/web/feasibility-study/ who certify the acceptability of the system. For example, system stakeholders for the Mentcare system include: 1. Patients whose information is recorded in the system and relatives of these patients. 2. Doctors who are responsible for assessing and treating patients. 3. Nurses who coordinate the consultations with doctors and administer some treatments. 4. Medical receptionists who manage patients’ appointments. 5. IT staff who are responsible for installing and maintaining the system. 6. A medical ethics manager who must ensure that the system meets current ethi- cal guidelines for patient care. 7. Health care managers who obtain management information from the system. 8. Medical records staff who are responsible for ensuring that system information can be maintained and preserved, and that record keeping procedures have been properly implemented. Requirements engineering is usually presented as the first stage of the software engineering process. However, some understanding of the system requirements may have to be developed before a decision is made to go ahead with the procurement or development of a system. This early-stage RE establishes a high-level view of what the system might do and the benefits that it might provide. These may then be con- sidered in a feasibility study, which tries to assess whether or not the system is tech- nically and financially feasible. The results of that study help management decide whether or not to go ahead with the procurement or development of the system. In this chapter, I present a “traditional” view of requirements rather than require- ments in agile processes, which I discussed in Chapter 3. For the majority of large systems, it is still the case that there is a clearly identifiable requirements engineering phase before implementation of the system begins. The outcome is a requirements document, which may be part of the system development contract. Of course, subsequent changes are made to the requirements, and user requirements may be expanded into  4.1 Functional and non-functional requirements 105 more detailed system requirements. Sometimes an agile approach of concurrently eliciting the requirements as the system is developed may be used to add detail and to refine the user requirements. 4.1 Functional and non-functional requirements Software system requirements are often classified as functional or non-functional requirements: 1. Functional requirements These are statements of services the system should provide, how the system should react to particular inputs, and how the system should behave in particular situations. In some cases, the functional require- ments may also explicitly state what the system should not do. 2. Non-functional requirements These are constraints on the services or functions offered by the system. They include timing constraints, constraints on the devel- opment process, and constraints imposed by standards. Non-functional require- ments often apply to the system as a whole rather than individual system features or services. In reality, the distinction between different types of requirements is not as clear- cut as these simple definitions suggest. A user requirement concerned with security, such as a statement limiting access to authorized users, may appear to be a non- functional requirement. However, when developed in more detail, this requirement may generate other requirements that are clearly functional, such as the need to include user authentication facilities in the system. This shows that requirements are not independent and that one requirement often generates or constrains other requirements. The system requirements therefore do not just specify the services or the features of the system that are required; they also specify the necessary functionality to ensure that these services/features are delivered effectively. 4.1.1 Functional requirements The functional requirements for a system describe what the system should do. These requirements depend on the type of software being developed, the expected users of the software, and the general approach taken by the organization when writing requirements. When expressed as user requirements, functional requirements should be written in natu- ral language so that system users and managers can understand them. Functional system requirements expand the user requirements and are written for system developers. They should describe the system functions, their inputs and outputs, and exceptions in detail. Functional system requirements vary from general requirements covering what the system should do to very specific requirements reflecting local ways of working or an organization’s existing systems. For example, here are examples of functional 106 Chapter 4 Requirements engineering Domain requirements Domain requirements are derived from the application domain of the system rather than from the specific needs of system users. They may be new functional requirements in their own right, constrain existing func- tional requirements, or set out how particular computations must be carried out. The problem with domain requirements is that software engineers may not understand the characteristics of the domain in which the system operates. This means that these engineers may not know whether or not a domain requirement has been missed out or conflicts with other requirements. http://software-engineering-book.com/web/domain-requirements/ requirements for the Mentcare system, used to maintain information about patients receiving treatment for mental health problems: 1. A user shall be able to search the appointments lists for all clinics. 2. The system shall generate each day, for each clinic, a list of patients who are expected to attend appointments that day. 3. Each staff member using the system shall be uniquely identified by his or her eight-digit employee number. These user requirements define specific functionality that should be included in the system. The requirements show that functional requirements may be written at different levels of detail (contrast requirements 1 and 3). Functional requirements, as the name suggests, have traditionally focused on what the system should do. However, if an organization decides that an existing off- the-shelf system software product can meet its needs, then there is very little point in developing a detailed functional specification. In such cases, the focus should be on the development of information requirements that specify the information needed for people to do their work. Information requirements specify the information needed and how it is to be delivered and organized. Therefore, an information requirement for the Mentcare system might specify what information is to be included in the list of patients expected for appointments that day. Imprecision in the requirements specification can lead to disputes between custom- ers and software developers. It is natural for a system developer to interpret an ambig- uous requirement in a way that simplifies its implementation. Often, however, this is not what the customer wants. New requirements have to be established and changes made to the system. Of course, this delays system delivery and increases costs. For example, the first Mentcare system requirement in the above list states that a user shall be able to search the appointments lists for all clinics. The rationale for this requirement is that patients with mental health problems are sometimes confused. They may have an appointment at one clinic but actually go to a different clinic. If they have an appointment, they will be recorded as having attended, regardless of the clinic.  4.1 Functional and non-functional requirements 107 A medical staff member specifying a search requirement may expect “search” to mean that, given a patient name, the system looks for that name in all appointments at all clinics. However, this is not explicit in the requirement. System developers may interpret the requirement so that it is easier to implement. Their search function may require the user to choose a clinic and then carry out the search of the patients who attended that clinic. This involves more user input and so takes longer to complete the search. Ideally, the functional requirements specification of a system should be both complete and consistent. Completeness means that all services and information required by the user should be defined. Consistency means that requirements should not be contradictory. In practice, it is only possible to achieve requirements consistency and complete- ness for very small software systems. One reason is that it is easy to make mistakes and omissions when writing specifications for large, complex systems. Another rea- son is that large systems have many stakeholders, with different backgrounds and expectations. Stakeholders are likely to have different—and often inconsistent— needs. These inconsistencies may not be obvious when the requirements are origi- nally specified, and the inconsistent requirements may only be discovered after deeper analysis or during system development. 4.1.2 Non-functional requirements Non-functional requirements, as the name suggests, are requirements that are not directly concerned with the specific services delivered by the system to its users. These non-functional requirements usually specify or constrain characteristics of the system as a whole. They may relate to emergent system properties such as reliability, response time, and memory use. Alternatively, they may define constraints on the system implementation, such as the capabilities of I/O devices or the data represen- tations used in interfaces with other systems. Non-functional requirements are often more critical than individual functional requirements. System users can usually find ways to work around a system function that doesn’t really meet their needs. However, failing to meet a non-functional requirement can mean that the whole system is unusable. For example, if an aircraft system does not meet its reliability requirements, it will not be certified as safe for operation; if an embedded control system fails to meet its performance requirements, the control functions will not operate correctly. While it is often possible to identify which system components implement spe- cific functional requirements (e.g., there may be formatting components that imple- ment reporting requirements), this is often more difficult with non-functional requirements. The implementation of these requirements may be spread throughout the system, for two reasons: 1. Non-functional requirements may affect the overall architecture of a system rather than the individual components. For example, to ensure that performance requirements are met in an embedded system, you may have to organize the system to minimize communications between components. 108 Chapter 4 Requirements engineering Non-functional requirements Product Organizational External requirements requirements requirements Efficiency Dependability Security Regulatory Ethical requirements requirements requirements requirements requirements Usability Environmental Operational Development Legislative requirements requirements requirements requirements requirements Performance Space Accounting Safety/security requirements requirements requirements requirements Figure 4.3 Types of non-functional 2. An individual non-functional requirement, such as a security requirement, may requirements generate several, related functional requirements that define new system ser- vices that are required if the non-functional requirement is to be implemented. In addition, it may also generate requirements that constrain existing require- ments; for example, it may limit access to information in the system. Nonfunctional requirements arise through user needs because of budget con- straints, organizational policies, the need for interoperability with other software or hardware systems, or external factors such as safety regulations or privacy legisla- tion. Figure 4.3 is a classification of non-functional requirements. You can see from this diagram that the non-functional requirements may come from required charac- teristics of the software (product requirements), the organization developing the software (organizational requirements), or external sources: 1. Product requirements These requirements specify or constrain the runtime behavior of the software. Examples include performance requirements for how fast the system must execute and how much memory it requires; reliability requirements that set out the acceptable failure rate; security requirements; and usability requirements. 2. Organizational requirements These requirements are broad system require- ments derived from policies and procedures in the customer’s and developer’s organizations. Examples include operational process requirements that define how the system will be used; development process requirements that specify the  4.1 Functional and non-functional requirements 109 PRODUCT REQUIREMENT The Mentcare system shall be available to all clinics during normal working hours (Mon–Fri, 08:30–17:30). Downtime within normal working hours shall not exceed 5 seconds in any one day. ORGANIZATIONAL REQUIREMENT Users of the Mentcare system shall identify themselves using their health authority identity card. EXTERNAL REQUIREMENT The system shall implement patient privacy provisions as set out in HStan-03-2006-priv. Figure 4.4 Examples of possible non-functional programming language; the development environment or process standards to requirements for the be used; and environmental requirements that specify the operating environ- Mentcare system ment of the system. 3. External requirements This broad heading covers all requirements that are derived from factors external to the system and its development process. These may include regulatory requirements that set out what must be done for the sys- tem to be approved for use by a regulator, such as a nuclear safety authority; legislative requirements that must be followed to ensure that the system oper- ates within the law; and ethical requirements that ensure that the system will be acceptable to its users and the general public. Figure 4.4 shows examples of product, organizational, and external requirements that could be included in the Mentcare system specification. The product require- ment is an availability requirement that defines when the system has to be available and the allowed downtime each day. It says nothing about the functionality of the Mentcare system and clearly identifies a constraint that has to be considered by the system designers. The organizational requirement specifies how users authenticate themselves to the system. The health authority that operates the system is moving to a standard authentication procedure for all software where, instead of users having a login name, they swipe their identity card through a reader to identify themselves. The external requirement is derived from the need for the system to conform to privacy legislation. Privacy is obviously a very important issue in health care systems, and the requirement specifies that the system should be developed in accordance with a national privacy standard. A common problem with non-functional requirements is that stakeholders pro- pose requirements as general goals, such as ease of use, the ability of the system to recover from failure, or rapid user response. Goals set out good intentions but cause problems for system developers as they leave scope for interpretation and subse- quent dispute once the system is delivered. For example, the following system goal is typical of how a manager might express usability requirements: The system should be easy to use by medical staff and should be organized in such a way that user errors are minimized. 110 Chapter 4 Requirements engineering Property Measure Speed Processed transactions/second User/event response time Screen refresh time Size Megabytes/Number of ROM chips Ease of use Training time Number of help frames Reliability Mean time to failure Probability of unavailability Rate of failure occurrence Availability Robustness Time to restart after failure Percentage of events causing failure Probability of data corruption on failure Portability Percentage of target dependent statements Number of target systems Figure 4.5 Metrics for specifying non- functional requirements I have rewritten this to show how the goal could be expressed as a “testable” non- functional requirement. It is impossible to objectively verify the system goal, but in the following description you can at least include software instrumentation to count the errors made by users when they are testing the system. Medical staff shall be able to use all the system functions after two hours of training. After this training, the average number of errors made by experienced users shall not exceed two per hour of system use. Whenever possible, you should write non-functional requirements quantitatively so that they can be objectively tested. Figure 4.5 shows metrics that you can use to specify non-functional system properties. You can measure these characteristics when the system is being tested to check whether or not the system has met its non- functional requirements. In practice, customers for a system often find it difficult to translate their goals into measurable requirements. For some goals, such as maintainability, there are no sim- ple metrics that can be used. In other cases, even when quantitative specification is possible, customers may not be able to relate their needs to these specifications. They don’t understand what some number defining the reliability (for example) means in terms of their everyday experience with computer systems. Furthermore, the cost of objectively verifying measurable, non-functional requirements can be very high, and the customers paying for the system may not think these costs are justified. Non-functional requirements often conflict and interact with other functional or non-functional requirements. For example, the identification requirement in Figure 4.4 requires a card reader to be installed with each computer that connects to the system. However, there may be another requirement that requests mobile access to the system from doctors’ or nurses’ tablets or smartphones. These are not normally  4.2 Requirements engineering processes 111 equipped with card readers so, in these circumstances, some alternative identifica- tion method may have to be supported. It is difficult to separate functional and non-functional requirements in the requirements document. If the non-functional requirements are stated separately from the functional requirements, the relationships between them may be hard to understand. However, you should, ideally, highlight requirements that are clearly related to emergent system properties, such as performance or reliability. You can do this by putting them in a separate section of the requirements document or by distin- guishing them, in some way, from other system requirements. Non-functional requirements such as reliability, safety, and confidentiality requirements are particularly important for critical systems. I cover these dependa- bility requirements in Part 2, which describes ways of specifying reliability, safety, and security requirements. 4.2 Requirements engineering processes As I discussed in Chapter 2, requirements engineering involves three key activities. These are discovering requirements by interacting with stakeholders (elicitation and analysis); converting these requirements into a standard form (specification); and checking that the requirements actually define the system that the customer wants (validation). I have shown these as sequential processes in Figure 2.4. However, in practice, requirements engineering is an iterative process in which the activities are interleaved. Figure 4.6 shows this interleaving. The activities are organized as an iterative process around a spiral. The output of the RE process is a system requirements docu- ment. The amount of time and effort devoted to each activity in an iteration depends on the stage of the overall process, the type of system being developed, and the budget that is available. Early in the process, most effort will be spent on understanding high-level business and non-functional requirements, and the user requirements for the system. Later in the process, in the outer rings of the spiral, more effort will be devoted to eliciting and understanding the non-functional requirements and more detailed system requirements. This spiral model accommodates approaches to development where the require- ments are developed to different levels of detail. The number of iterations around the spiral can vary so that the spiral can be exited after some or all of the user require- ments have been elicited. Agile development can be used instead of prototyping so that the requirements and the system implementation are developed together. In virtually all systems, requirements change. The people involved develop a bet- ter understanding of what they want the software to do; the organization buying the system changes; and modifications are made to the system’s hardware, software, and organizational environment. Changes have to be managed to understand the impact on other requirements and the cost and system implications of making the change. I discuss this process of requirements management in Section 4.6. 112 Chapter 4 Requirements engineering Requirements specification System requirements specification and modeling User requirements specification Business requirements specification Start Feasibility System study Requirements req. Requirements elicitation elicitation User validation requirements elicitation Prototyping Reviews Figure 4.6 A spiral view of the requirements System requirements engineering process document 4.3 Requirements elicitation The aims of the requirements elicitation process are to understand the work that stakeholders do and how they might use a new system to help support that work. During requirements elicitation, software engineers work with stakeholders to find out about the application domain, work activities, the services and system features that stakeholders want, the required performance of the system, hardware con- straints, and so on. Eliciting and understanding requirements from system stakeholders is a difficult process for several reasons: 1. Stakeholders often don’t know what they want from a computer system except in the most general terms; they may find it difficult to articulate what they want the system to do; they may make unrealistic demands because they don’t know what is and isn’t feasible.  4.3 Requirements elicitation 113 1. Requirements discovery and understanding 4. Requirements 2. Requirements documentation classification and organization 3. Requirements Figure 4.7 The prioritization and requirements elicitation negotiation and analysis process 2. Stakeholders in a system naturally express requirements in their own terms and with implicit knowledge of their own work. Requirements engineers, without experience in the customer’s domain, may not understand these requirements. 3. Different stakeholders, with diverse requirements, may express their require- ments in different ways. Requirements engineers have to discover all potential sources of requirements and discover commonalities and conflict. 4. Political factors may influence the requirements of a system. Managers may demand specific system requirements because these will allow them to increase their influence in the organization. 5. The economic and business environment in which the analysis takes place is dynamic. It inevitably changes during the analysis process. The importance of particular requirements may change. New requirements may emerge from new stakeholders who were not originally consulted. A process model of the elicitation and analysis process is shown in Figure 4.7. Each organization will have its own version or instantiation of this general model, depending on local factors such as the expertise of the staff, the type of system being developed, and the standards used. The process activities are: 1. Requirements discovery and understanding This is the process of interacting with stakeholders of the system to discover their requirements. Domain requirements from stakeholders and documentation are also discovered during this activity. 2. Requirements classification and organization This activity takes the unstruc- tured collection of requirements, groups related requirements and organizes them into coherent clusters. 3. Requirements prioritization and negotiation Inevitably, when multiple stake- holders are involved, requirements will conflict. This activity is concerned with prioritizing requirements and finding and resolving requirements conflicts 114 Chapter 4 Requirements engineering Viewpoints A viewpoint is a way of collecting and organizing a set of requirements from a group of stakeholders who have something in common. Each viewpoint therefore includes a set of system requirements. Viewpoints might come from end-users, managers, or others. They help identify the people who can provide information about their requirements and structure the requirements for analysis. http://www.software-engineering-book.com/web/viewpoints/ through negotiation. Usually, stakeholders have to meet to resolve differences and agree on compromise requirements. 4. Requirements documentation The requirements are documented and input into the next round of the spiral. An early draft of the software requirements docu- ments may be produced at this stage, or the requirements may simply be main- tained informally on whiteboards, wikis, or other shared spaces. Figure 4.7 shows that requirements elicitation and analysis is an iterative process with continual feedback from each activity to other activities. The process cycle starts with requirements discovery and ends with the requirements documentation. The analyst’s understanding of the requirements improves with each round of the cycle. The cycle ends when the requirements document has been produced. To simplify the analysis of requirements, it is helpful to organize and group the stakeholder information. One way of doing so is to consider each stakeholder group to be a viewpoint and to collect all requirements from that group into the viewpoint. You may also include viewpoints to represent domain requirements and constraints from other systems. Alternatively, you can use a model of the system architecture to identify subsystems and to associate requirements with each subsystem. Inevitably, different stakeholders have different views on the importance and pri- ority of requirements, and sometimes these views are conflicting. If some stakehold- ers feel that their views have not been properly considered, then they may deliberately attempt to undermine the RE process. Therefore, it is important that you organize regular stakeholder meetings. Stakeholders should have the opportunity to express their concerns and agree on requirements compromises. At the requirements documentation stage, it is important that you use simple lan- guage and diagrams to describe the requirements. This makes it possible for stake- holders to understand and comment on these requirements. To make information sharing easier, it is best to use a shared document (e.g., on Google Docs or Office 365) or a wiki that is accessible to all interested stakeholders. 4.3.1 Requirements elicitation techniques Requirements elicitation involves meeting with stakeholders of different kinds to discover information about the proposed system. You may supplement this information  4.3 Requirements elicitation 115 with knowledge of existing systems and their usage and information from docu- ments of various kinds. You need to spend time understanding how people work, what they produce, how they use other systems, and how they may need to change to accommodate a new system. There are two fundamental approaches to requirements elicitation: 1. Interviewing, where you talk to people about what they do. 2. Observation or ethnography, where you watch people doing their job to see what artifacts they use, how they use them, and so on. You should use a mix of interviewing and observation to collect information and, from that, you derive the requirements, which are then the basis for further discussions. 4.3.1.1 Interviewing Formal or informal interviews with system stakeholders are part of most require- ments engineering processes. In these interviews, the requirements engineering team puts questions to stakeholders about the system that they currently use and the sys- tem to be developed. Requirements are derived from the answers to these questions. Interviews may be of two types: 1. Closed interviews, where the stakeholder answers a predefined set of questions. 2. Open interviews, in which there is no predefined agenda. The requirements engineering team explores a range of issues with system stakeholders and hence develops a better understanding of their needs. In practice, interviews with stakeholders are normally a mixture of both of these. You may have to obtain the answer to certain questions, but these usually lead to other issues that are discussed in a less structured way. Completely open-ended dis- cussions rarely work well. You usually have to ask some questions to get started and to keep the interview focused on the system to be developed. Interviews are good for getting an overall understanding of what stakeholders do, how they might interact with the new system, and the difficulties that they face with current systems. People like talking about their work, and so they are usually happy to get involved in interviews. However, unless you have a system prototype to dem- onstrate, you should not expect stakeholders to suggest specific and detailed require- ments. Everyone finds it difficult to visualize what a system might be like. You need to analyze the information collected and to generate the requirements from this. Eliciting domain knowledge through interviews can be difficult, for two reasons: 1. All application specialists use jargon specific to their area of work. It is impos- sible for them to discuss domain requirements without using this terminology. They normally use words in a precise and subtle way that requirements engi- neers may misunderstand. 116 Chapter 4 Requirements engineering 2. Some domain knowledge is so familiar to stakeholders that they either find it difficult to explain or they think it is so fundamental that it isn’t worth mention- ing. For example, for a librarian, it goes without saying that all acquisitions are catalogued before they are added to the library. However, this may not be obvi- ous to the interviewer, and so it isn’t taken into account in the requirements. Interviews are not an effective technique for eliciting knowledge about organiza- tional requirements and constraints because there are subtle power relationships between the different people in the organization. Published organizational structures rarely match the reality of decision making in an organization, but interviewees may not wish to reveal the actual rather than the theoretical structure to a stranger. In general, most people are generally reluctant to discuss political and organizational issues that may affect the requirements. To be an effective interviewer, you should bear two things in mind: 1. You should be open-minded, avoid preconceived ideas about the requirements, and willing to listen to stakeholders. If the stakeholder comes up with surprising requirements, then you should be willing to change your mind about the system. 2. You should prompt the interviewee to get discussions going by using a spring- board question or a requirements proposal, or by working together on a proto- type system. Saying to people “tell me what you want” is unlikely to result in useful information. They find it much easier to talk in a defined context rather than in general terms. Information from interviews is used along with other information about the sys- tem from documentation describing business processes or existing systems, user observations, and developer experience. Sometimes, apart from the information in the system documents, the interview information may be the only source of informa- tion about the system requirements. However, interviewing on its own is liable to miss essential information, and so it should be used in conjunction with other requirements elicitation techniques. 4.3.1.2 Ethnography Software systems do not exist in isolation. They are used in a social and organiza- tional environment, and software system requirements may be generated or con- strained by that environment. One reason why many software systems are delivered but never used is that their requirements do not take proper account of how social and organizational factors affect the practical operation of the system. It is therefore very important that, during the requirements engineering process, you try to under- stand the social and organizational issues that affect the use of the system. Ethnography is an observational technique that can be used to understand opera- tional processes and help derive requirements for software to support these pro- cesses. An analyst immerses himself or herself in the working environment where  4.3 Requirements elicitation 117 the system will be used. The day-to-day work is observed, and notes are made of the actual tasks in which participants are involved. The value of ethnography is that it helps discover implicit system requirements that reflect the actual ways that people work, rather than the formal processes defined by the organization. People often find it very difficult to articulate details of their work because it is second nature to them. They understand their own work but may not understand its relationship to other work in the organization. Social and organizational factors that affect the work, but that are not obvious to individuals, may only become clear when noticed by an unbiased observer. For example, a workgroup may self-organize so that members know of each other’s work and can cover for each other if someone is absent. This may not be mentioned during an interview as the group might not see it as an integral part of their work. Suchman (Suchman 1983) pioneered the use of ethnography to study office work. She found that actual work practices were far richer, more complex, and more dynamic than the simple models assumed by office automation systems. The differ- ence between the assumed and the actual work was the most important reason why these office systems had no significant effect on productivity. Crabtree (Crabtree 2003) discusses a wide range of studies since then and describes, in general, the use of ethnography in systems design. In my own research, I have investigated methods of integrating ethnography into the software engineering process by linking it with requirements engineering methods (Viller and Sommerville 2000) and documenting patterns of interaction in cooperative systems (Martin and Sommerville 2004). Ethnography is particularly effective for discovering two types of requirements: 1. Requirements derived from the way in which people actually work, rather than the way in which business process definitions say they ought to work. In prac- tice, people never follow formal processes. For example, air traffic controllers may switch off a conflict alert system that detects aircraft with intersecting flight paths, even though normal control procedures specify that it should be used. The conflict alert system is sensitive and issues audible warnings even when planes are far apart. Controllers may find these distracting and prefer to use other strategies to ensure that planes are not on conflicting flight paths. 2. Requirements derived from cooperation and awareness of other people’s activi- ties. For example, air traffic controllers (ATCs) may use an awareness of other controlles’ work to predict the number of aircraft that will be entering their con- trol sector. They then modify their control strategies depending on that pre- dicted workload. Therefore, an automated ATC system should allow controllers in a sector to have some visibility of the work in adjacent sectors. Ethnography can be combined with the development of a system prototype (Figure 4.8). The ethnography informs the development of the prototype so that fewer prototype refinement cycles are required. Furthermore, the prototyping focuses the ethnography by identifying problems and questions that can then be dis- cussed with the ethnographer. He or she should then look for the answers to these questions during the next phase of the system study (Sommerville et al. 1993). 118 Chapter 4 Requirements engineering Ethnographic Debriefing Focused analysis meetings ethnography Prototype evaluation Figure 4.8 Ethnography Generic system System and prototyping for development protoyping requirements analysis Ethnography is helpful to understand existing systems, but this understanding does not always help with innovation. Innovation is particularly relevant for new product development. Commentators have suggested that Nokia used ethnography to discover how people used their phones and developed new phone models on that basis; Apple, on the other hand, ignored current use and revolutionized the mobile phone industry with the introduction of the iPhone. Ethnographic studies can reveal critical process details that are often missed by other requirements elicitation techniques. However, because of its focus on the end- user, this approach is not effective for discovering broader organizational or domain requirements or for suggestion innovations. You therefore have to use ethnography as one of a number of techniques for requirements elicitation. 4.3.2 Stories and scenarios People find it easier to relate to real-life examples than abstract descriptions. They are not good at telling you the system requirements. However, they may be able to describe how they handle particular situations or imagine things that they might do in a new way of working. Stories and scenarios are ways of capturing this kind of information. You can then use these when interviewing groups of stakeholders to discuss the system with other stakeholders and to develop more specific system requirements. Stories and scenarios are essentially the same thing. They are a description of how the system can be used for some particular task. They describe what people do, what information they use and produce, and what systems they may use in this process. The difference is in the ways that descriptions are structured and in the level of detail presented. Stories are written as narrative text and present a high-level description of system use; scenarios are usually structured with specific information collected such as inputs and outputs. I find stories to be effective in setting out the “big picture.” Parts of stories can then be developed in more detail and represented as scenarios. Figure 4.9 is an example of a story that I developed to understand the requirements for the iLearn digital learning environment that I introduced in Chapter 1. This story describes a situation in a primary (elementary) school where the teacher is using the environment to support student projects on the fishing industry. You can see this is a very high-level description. Its purpose is to facilitate discussion of how the iLearn system might be used and to act as a starting point for eliciting the requirements for that system.  4.3 Requirements elicitation 119 Photo sharing in the classroom Jack is a primary school teacher in Ullapool (a village in northern Scotland). He has decided that a class project should be focused on the fishing industry in the area, looking at the history, development, and economic impact of fishing. As part of this project, pupils are asked to gather and share reminiscences from relatives, use newspa- per archives, and collect old photographs related to fishing and fishing communities in the area. Pupils use an iLearn wiki to gather together fishing stories and SCRAN (a history resources site) to access newspaper archives and photographs. However, Jack also needs a photo-sharing site because he wants pupils to take and comment on each other’s photos and to upload scans of old photographs that they may have in their families. Jack sends an email to a primary school teachers’ group, which he is a member of, to see if anyone can rec- ommend an appropriate system. Two teachers reply, and both suggest that he use KidsTakePics, a photo-sharing site that allows teachers to check and moderate content. As KidsTakePics is not integrated with the iLearn authentication service, he sets up a teacher and a class account. He uses the iLearn setup service to add KidsTakePics to the services seen by the pupils in his class so that when they log in, they can immediately use the system to upload photos from their mobile devices and class computers. Figure 4.9 A user story for the iLearn system The advantage of stories is that everyone can easily relate to them. We found this approach to be particularly useful to get information from a wider community than we could realistically interview. We made the stories available on a wiki and invited teachers and students from across the country to comment on them. These high-level stories do not go into detail about a system, but they can be developed into more specific scenarios. Scenarios are descriptions of example user interaction sessions. I think that it is best to present scenarios in a structured way rather than as narrative text. User stories used in agile methods such as Extreme Programming, are actually narrative scenarios rather than general stories to help elicit requirements. A scenario starts with an outline of the interaction. During the elicitation process, details are added to create a complete description of that interaction. At its most general, a scenario may include: 1. A description of what the system and users expect when the scenario starts. 2. A description of the normal flow of events in the scenario. 3. A description of what can go wrong and how resulting problems can be handled. 4. Information about other activities that might be going on at the same time. 5. A description of the system state when the scenario ends. As an example of a scenario, Figure 4.10 describes what happens when a student uploads photos to the KidsTakePics system, as explained in Figure 4.9. The key dif- ference between this system and other systems is that a teacher moderates the uploaded photos to check that they are suitable for sharing. You can see this is a much more detailed description than the story in Figure 4.9, and so it can be used to propose requirements for the iLearn system. Like stories, scenarios can be used to facilitate discussions with stakeholders who sometimes may have different ways of achieving the same result. 120 Chapter 4 Requirements engineering Uploading photos to KidsTakePics Initial assumption: A user or a group of users have one or more digital photographs to be uploaded to the picture-sharing site. These photos are saved on either a tablet or a laptop computer. They have successfully logged on to KidsTakePics. Normal: The user chooses to upload photos and is prompted to select the photos to be uploaded on the computer and to select the project name under which the photos will be stored. Users should also be given the option of inputting keywords that should be associated with each uploaded photo. Uploaded photos are named by creating a conjunction of the user name with the filename of the photo on the local computer. On completion of the upload, the system automatically sends an email to the project moderator, asking them to check new content, and generates an on-screen message to the user that this checking has been done. What can go wrong: No moderator is associated with the selected project. An email is automatically generated to the school administrator asking them to nominate a project moderator. Users should be informed of a possible delay in making their photos visible. Photos with the same name have already been uploaded by the same user. The user should be asked if he or she wishes to re-upload the photos with the same name, rename the photos, or cancel the upload. If users choose to re-upload the photos, the originals are overwritten. If they choose to rename the photos, a new name is automatically generated by adding a number to the existing filename. Other activities: The moderator may be logged on to the system and may approve photos as they are uploaded. System state on completion: User is logged on. The selected photos have been uploaded and assigned a status “awaiting moderation.” Photos are visible to the moderator and to the user who uploaded them. Figure 4.10 Scenario for uploading photos in KidsTakePics 4.4 Requirements specification Requirements specification is the process of writing down the user and system require- ments in a requirements document. Ideally, the user and system requirements should be clear, unambiguous, easy to understand, complete, and consistent. In practice, this is almost impossible to achieve. Stakeholders interpret the requirements in different ways, and there are often inherent conflicts and inconsistencies in the requirements. User requirements are almost always written in natural language supplemented by appropriate diagrams and tables in the requirements document. System require- ments may also be written in natural language, but other notations based on forms, graphical, or mathematical system models can also be used. Figure 4.11 summarizes possible notations for writing system requirements. The user requirements for a system should describe the functional and nonfunctional requirements so that they are understandable by system users who don’t have detailed technical knowledge. Ideally, they should specify only the external behavior of the sys- tem. The requirements document should not include details of the system architecture or design. Consequently, if you are writing user requirements, you should not use soft- ware jargon, structured notations, or formal notations. You should write user require- ments in natural language, with simple tables, forms, and intuitive diagrams.  4.4 Requirements specification 121 Notation Description Natural language The requirements are written using numbered sentences in natural language. sentences Each sentence should express one requirement. Structured natural The requirements are written in natural language on a standard form or language template. Each field provides information about an aspect of the requirement. Graphical notations Graphical models, supplemented by text annotations, are used to define the functional requirements for the system. UML (unified modeling language) use case and sequence diagrams are commonly used. Mathematical These notations are based on mathematical concepts such as finite-state specifications machines or sets. Although these unambiguous specifications can reduce the ambiguity in a requirements document, most customers don’t understand a formal specification. They cannot check that it represents what they want, and they are reluctant to accept it as a system contract. (I discuss this approach, in Chapter 10, which covers system dependability.) Figure 4.11 Notations for writing system System requirements are expanded versions of the user requirements that soft- requirements ware engineers use as the starting point for the system design. They add detail and explain how the system should provide the user requirements. They may be used as part of the contract for the implementation of the system and should therefore be a complete and detailed specification of the whole system. Ideally, the system requirements should only describe the external behavior of the system and its operational constraints. They should not be concerned with how the system should be designed or implemented. However, at the level of detail required to completely specify a complex software system, it is neither possible nor desirable to exclude all design information. There are several reasons for this: 1. You may have to design an initial architecture of the system to help structure the requirements specification. The system requirements are organized according to the different subsystems that make up the system. We did this when we were defining the requirements for the iLearn system, where we proposed the archi- tecture shown in Figure 1.8. 2. In most cases, systems must interoperate with existing systems, which constrain the design and impose requirements on the new system. 3. The use of a specific architecture to satisfy non-functional requirements, such as N-version programming to achieve reliability, discussed in Chapter 11, may be necessary. An external regulator who needs to certify that the system is safe may specify that an architectural design that has already been certified should be used. 4.4.1 Natural language specification Natural language has been used to write requirements for software since the 1950s. It is expressive, intuitive, and universal. It is also potentially vague and ambiguous, and its interpretation depends on the background of the reader. As a result, there 122 Chapter 4 Requirements engineering 3.2 The system shall measure the blood sugar and deliver insulin, if required, every 10 minutes. (Changes in blood sugar are relatively slow, so more frequent measurement is unnecessary; less frequent measurement could lead to unnecessarily high sugar levels.) 3.6 The system shall run a self-test routine every minute with the conditions to be tested and the associated actions defined in Table 1. (A self-test routine can discover hardware and software problems and alert the user to the fact the normal operation may be impossible.) Figure 4.12 Example have been many proposals for alternative ways to write requirements. However, requirements for the insulin pump software none of these proposals has been widely adopted, and natural language will continue system to be the most widely used way of specifying system and software requirements. To minimize misunderstandings when writing natural language requirements, I recommend that you follow these simple guidelines: 1. Invent a standard format and ensure that all requirement definitions adhere to that format. Standardizing the format makes omissions less likely and requirements easier to check. I suggest that, wherever possible, you should write the requirement in one or two sentences of natural language. 2. Use language consistently to distinguish between mandatory and desirable requirements. Mandatory requirements are requirements that the system must support and are usually written using “shall.” Desirable requirements are not essential and are written using “should.” 3. Use text highlighting (bold, italic, or color) to pick out key parts of the requirement. 4. Do not assume that readers understand technical, software engineering language. It is easy for words such as “architecture” and “module” to be misunderstood. Wherever possible, you should avoid the use of jargon, abbreviations, and acronyms. 5. Whenever possible, you should try to associate a rationale with each user requirement. The rationale should explain why the requirement has been included and who proposed the requirement (the requirement source), so that you know whom to consult if the requirement has to be changed. Requirements rationale is particularly useful when requirements are changed, as it may help decide what changes would be undesirable. Figure 4.12 illustrates how these guidelines may be used. It includes two require- ments for the embedded software for the automated insulin pump, introduced in Chapter 1. Other requirements for this embedded system are defined in the insulin pump requirements document, which can be downloaded from the book’s web pages. 4.4.2 Structured specifications Structured natural language is a way of writing system requirements where require- ments are written in a standard way rather than as free-form text. This approach maintains most of the expressiveness and understandability of natural language but  4.4 Requirements specification 123 Problems with using natural language for requirements specification The flexibility of natural language, which is so useful for specification, often causes problems. There is scope for writing unclear requirements, and readers (the designers) may misinterpret requirements because they have a different background to the user. It is easy to amalgamate several requirements into a single sentence, and structuring natural language requirements can be difficult. http://software-engineering-book.com/web/natural-language/ ensures that some uniformity is imposed on the specification. Structured language notations use templates to specify system requirements. The specification may use programming language constructs to show alternatives and iteration, and may high- light key elements using shading or different fonts. The Robertsons (Robertson and Robertson 2013), in their book on the VOLERE requirements engineering method, recommend that user requirements be initially written on cards, one requirement per card. They suggest a number of fields on each card, such as the requirements rationale, the dependencies on other requirements, the source of the requirements, and supporting materials. This is similar to the approach used in the example of a structured specification shown in Figure 4.13. To use a structured approach to specifying system requirements, you define one or more standard templates for requirements and represent these templates as struc- tured forms. The specification may be structured around the objects manipulated by the system, the functions performed by the system, or the events processed by the system. An example of a form-based specification, in this case, one that defines how to calculate the dose of insulin to be delivered when the blood sugar is within a safe band, is shown in Figure 4.13. When a standard format is used for specifying functional requirements, the fol- lowing information should be included: 1. A description of the function or entity being specified. 2. A description of its inputs and the origin of these inputs. 3. A description of its outputs and the destination of these outputs. 4. Information about the information needed for the computation or other entities in the system that are required (the “requires” part). 5. A description of the action to be taken. 6. If a functional approach is used, a precondition setting out what must be true before the function is called, and a postcondition specifying what is true after the function is called. 7. A description of the side effects (if any) of the operation. Using structured specifications removes some of the problems of natural language specification. Variability in the specification is reduced, and requirements are organized 124 Chapter 4 Requirements engineering Insulin Pump/Control Software/SRS/3.3.2 Function Compute insulin dose: Safe sugar level. Description Computes the dose of insulin to be delivered when the current measured sugar level is in the safe zone between 3 and 7 units. Inputs Current sugar reading (r2), the previous two readings (r0 and r1). Source Current sugar reading from sensor. Other readings from memory. Outputs CompDose—the dose in insulin to be delivered. Destination Main control loop. Action: CompDose is zero if the sugar level is stable or falling or if the level is increasing but the rate of increase is decreasing. If the level is increasing and the rate of increase is increasing, then CompDose is computed by dividing the difference between the current sugar level and the previous level by 4 and rounding the result. If the result, is rounded to zero then CompDose is set to the minimum dose that can be delivered. (see Figure 4.14) Requires Two previous readings so that the rate of change of sugar level can be computed. Precondition The insulin reservoir contains at least the maximum allowed single dose of insulin. Postcondition r0 is replaced by r1 then r1 is replaced by r2. Side effects None. Figure 4.13 The structured specification of a requirement for more effectively. However, it is still sometimes difficult to write requirements in a an insulin pump clear and unambiguous way, particularly when complex computations (e.g., how to calculate the insulin dose) are to be specified. To address this problem, you can add extra information to natural language requirements, for example, by using tables or graphical models of the system. These can show how computations proceed, how the system state changes, how users inter- act with the system, and how sequences of actions are performed. Tables are particularly useful when there are a number of possible alternative situations and you need to describe the actions to be taken for each of these. The insulin pump bases its computations of the insulin requirement on the rate of change of blood sugar levels. The rates of change are computed using the current and previ- Figure 4.14 The ous readings. Figure 4.14 is a tabular description of how the rate of change of blood tabular specification sugar is used to calculate the amount of insulin to be delivered. of computation in an insulin pump Condition Action Sugar level falling (r2 6 r1) CompDose = 0 Sugar level stable (r2 = r1) CompDose = 0 Sugar level increasing and rate of increase CompDose = 0 decreasing ((r2 - r1)