6.3. Software Requirements Specification A software requirements specification (SRS) is a complete description of the behavior of the software to be developed. It includes a set of use cases that describe all of the interactions that the users will have with the software. In addition to use cases, the SRS contains functional requirements, which define the internal workings of the software: that is, the calculations, technical details, data manipulation and processing, and other specific functionality that shows how the use cases are to be satisfied. It also contains nonfunctional requirements, which impose constraints on the design or implementation (such as performance requirements, quality standards, or design constraints). The SRS is the most important work product that is produced by the requirements engineering project activities. All later work productssoftware design and architecture, code, test plansare based on the SRS. 6.3.1. SRS Template The SRS contains the use cases, functional requirements, and nonfunctional requirements. It should also contain overall information about the project, in order to orient the team. Table 6-8 shows the SRS template . Table 6-8. Software requirements specification outline Introduction Purpose Scope System overview References
Definitions Use cases Functional requirements Nonfunctional requirements
|
The introduction serves to orient the reader. It describes both the system and the SRS itself:
Purpose This section describes the purpose of the document. Typically, this will contain a brief two- or three-sentence description, including the name of the project. For example: "The purpose of this document is to serve as a guide to designers, developers, and testers who are responsible for the engineering of the (name of project) project. It should give the engineers all of the information necessary to design, develop, and test the software." This is to ensure that the person reading the document understands what he or she is looking at.
Scope This section contains a brief description of the scope of the document. If the SRS is a complete description of the software, then it will state something similar to: "This document contains a complete description of the functionality of the (name of project) project. It consists of use cases, functional requirements , and nonfunctional requirements, which, taken together, form a complete description of the software." For complex software, the requirements for the project might be divided into several SRS documents. In this case, the scope should indicate which portion of the project is covered in this document.
System overview This section contains a description of the system. This is essentially a brief summary of the vision and scope of the project.
References Any references to other documents (including the vision and scope document) should be included here. These may include other documents in the organization, work products, articles, and anything else that is relevant to understanding the SRS. If there is an organizational intranet, this section often includes URLs of referenced documents.
Definitions The "Definitions" section contains any definitions needed to understand the SRS. Often, it will contain a glossary, defining terms that the reader may not be familiar with (or that may have a specific meaning here that differs from everyday use). This section may also contain definitions of any data files that are used as input, a list of any databases that may be needed, and any other organizational or workflow-related information that is needed to understand the SRS.
The remaining sections contain a complete description of the behavior of the software. The "Use Cases" section contains each of the use cases. Each use case is represented by a table, which is in the format shown in Table 6-6. The "Functional requirements" section contains the functional requirements, and the "Nonfunctional requirements" section contains the nonfunctional requirements. Each functional and nonfunctional requirement is added to the SRS as a table (using the format shown in Table 6-9). The SRS should also contain a complete table of contents that includes the name and number of each use case, functional requirement, and nonfunctional requirement. 6.3.1.1. Functional requirements Once an initial set of use cases has been created and filled in, the requirements analyst begins documenting the functional requirements. Table 6-9 shows the template for a functional requirement. Table 6-9. Functional and nonfunctional requirement templateName | Name and number of the functional requirement | Summary | Brief description of the requirement | Rationale | Description of the reason that the requirement is needed | Requirements | The behavior that is required of the software | References | Use cases and other functional and nonfunctional requirements that are relevant to understanding this one |
The name, summary, and rationale of each functional requirement are used in the same way as those of the use cases. The behavior that is to be implemented should be described in plain English in the "Requirements" section. Most requirements are only relevant to a small number of use casesthese should be listed by name and number in the "References" section. (Some requirements are not associated with use cases.) The core of the requirement is the description of the required behavior. It is very important to make this clear and readable. This behavior may come from organizational or business rules, or it may be discovered through elicitation sessions with users, stakeholders, and other experts within the organization. Many requirements will be uncovered during the use case development. When this happens, the requirements analyst should create a placeholder requirement with a name and summary, and research the details later, to be filled in when they are better known. Table 6-10 shows an example of a requirement that might be discovered during the development of the search-and-replace use case in Table 6-6. Table 6-10. Functional requirement exampleName | FR-4: Case sensitivity in search-and-replace |
|---|
Summary | The search-and-replace feature must have case sensitivity in both the search and the replacement. | Rationale | A user will often search for a word that is part of a sentence, title, heading, or other kind of text that is not all lowercase. The search-and-replace function needs to be aware of that, and give the user the option to ignore it. | Requirements | When a user invokes the search-and-replace function, the software must give the option to do a case-sensitive search. By default, the search will match any text that has the same letters as the search term, even if the case is different. If the user indicates that the search is to be done with case-sensitivity turned on, then the software will only match text in the document where the case is identical to that of the search term. During a search and replace, when the software replaces original text in the document with the replacement text specified by the user, the software retains the case of the original text as follows: If the original text was all uppercase, then the replacement text must be inserted in all uppercase. If the original text was all lowercase, then the replacement text must be inserted in all lowercase. If the original text had the first character uppercase and the rest of the characters lowercase, then the replacement text must reflect this case as well. If the original text was sentence case (where the first letter of each word is uppercase), then the replacement text must be inserted in sentence case. In all other cases, the replacement text should be inserted using the case specified by the user.
| References | UC-8: Search |
The behavior in the requirement can contain lists, bullets, equations, pictures, references to external documents, and any other material that will help the reader understand what needs to be implemented. The goal of the requirement is to communicate this behavior in as clear and unambiguous a manner as possible. One pitfall is to get hung up on ambiguity. For example, the example above refers to "the same letters as the search term." This is potentially ambiguousan overly pedantic reading could interpret it to mean "the same letters as the search term but in any order," and that would technically be correct because the requirement does not specify that the letters should not be out of order. However, it is unlikely that the text will be read that way. In this case, all of the developers will almost certainly understand what the requirements analyst meant when the text was written, and writing the extra explanation into the requirement could make it more confusing. The requirements analyst has a great deal of discretion about how to break requirements up. For example, the example above could potentially be broken into two separate requirements, with one requirement allowing for a case-sensitive search and another specifying that the replacement text needs to retain the case of the original text when the search is not case-sensitive. A good general rule is that requirements should only be split up when that split offers more clarity. In this case, a split probably would not make the requirement any clearer, so keeping these together makes sense. Many requirements define behavior that the user can turn on or off (like the user's ability to specify a case-sensitive search in the example). In this case, the requirement should always specify the default behavior (in the example case, the default search is case-insensitive). Requirements often specify behavior that only occurs under certain conditions (like the conditions in which the case is retained). It is also important to specify a fall-through case to show what happens if none of the specified conditions are met ("In all other cases..."). As with the use case, the requirements should not contain any design elements. The requirements analyst should avoid words like window, button, click, checkbox, radio button, form, etc. For example, many search-and-replace features use a checkbox to implement context-sensitive searching. But there is no need to require that the designer use a checkboxit's possible that an innovative designer might come up with a better way to let the user turn on case-sensitive searching (like with two separate buttons, a radio button, a separate tab, or some other way that isn't immediately obvious). Leaving the design unconstrained allows the designers and programmers more freedom to implement the requirements creatively. The more that the design is constrained in the SRS, the harder it makes their jobs. 6.3.1.2. Nonfunctional requirements Users have implicit expectations about how well the software will work. These characteristics include how easy the software is to use, how quickly it executes, how reliable it is, and how well it behaves when unexpected conditions arise. The nonfunctional requirements define these aspects about the system. (The nonfunctional requirements are sometimes referred to as "nonbehavioral requirements" or "software quality attributes.") The nonfunctional requirements should be defined as precisely as possible. Often, this is done by quantifying them. Where possible, the nonfunctional requirements should provide specific measurements that the software must meet. The maximum number of seconds it must take to perform a task, the maximum size of a database on disk, the number of hours per day a system must be available, and the number of concurrent users supported are examples of requirements that the software must implement but do not change its behavior. There are many kinds of nonfunctional requirements, including:
Availability A system's availability, or "uptime," is the amount of time that it is operational and available for use. This is specified because some systems are designed with expected downtime for activities like database upgrades and backups.
Efficiency Specifies how well the software utilizes scarce resources: CPU cycles, disk space, memory, bandwidth, etc.
Flexibility If the organization intends to increase or extend the functionality of the software after it is deployed, that should be planned from the beginning; it influences choices made during the design, development, testing, and deployment of the system.
Portability Portability specifies the ease with which the software can be installed on all necessary platforms, and the platforms on which it is expected to run.
Integrity Integrity requirements define the security attributes of the system, restricting access to features or data to certain users and protecting the privacy of data entered into the software.
Performance The performance constraints specify the timing characteristics of the software. Certain tasks or features are more time-sensitive than others; the nonfunctional requirements should identify those software functions that have constraints on their performance.
Reliability Reliability specifies the capability of the software to maintain its performance over time. Unreliable software fails frequently, and certain tasks are more sensitive to failure (for example, because they cannot be restarted, or because they must be run at a certain time).
Reusability Many systems are developed with the ability to leverage common components across multiple products. Reusability indicates the extent to which software components should be designed in such a way that they can be used in applications other than the ones for which they were initially developed.
Robustness A robust system is able to handle error conditions gracefully, without failure. This includes a tolerance of invalid data, software defects, and unexpected operating conditions.
Scalability Software that is scalable has the ability to handle a wide variety of system configuration sizes. The nonfunctional requirements should specify the ways in which the system may be expected to scale up (by increasing hardware capacity, adding machines, etc.).
Usability Ease-of-use requirements address the factors that constitute the capacity of the software to be understood, learned, and used by its intended users.
The nonfunctional requirements can use the same template as the functional requirements. Table 6-11 shows an example of a nonfunctional requirement: Table 6-11. Nonfunctional requirement exampleName | NF-7: Performance constraints for search-and-replace |
|---|
Summary | The search-and-replace feature must perform a search quickly. | Rationale | If a search is not fast enough, users will avoid using the software. | Requirements | A case-insensitive search-and-replace performed on a 3MB document with twenty 30-character search terms to be replaced with a different 30-character search term must take under 500ms on a 700MHz Pentium III running Microsoft Windows 2000 at 50% CPU load. | References | UC-8: Search. |
6.3.2. Develop the SRS Iteratively Like use cases, the SRS should be developed in a highly iterative manner. Table 6-12 shows the SRS development script, an iterative process that guides a requirements analyst through the development of a software requirements specification. Table 6-12. SRS development scriptName | Software requirements specification development script |
|---|
Purpose | To elicit software requirements, document them in a software requirements specification, and verify that it is correct. | Summary | The development of the software requirements specification should be the most iterative part of the entire project. This is the point where the behavior of the software to be developed is at its most malleableit has only been described in words, and has not yet been realized in design, architecture, code, test plans, or any other work product. The goal of this script is to ensure that as many defects are found as possible, because each defect missed at this stage will be much more costly to detect and fix later on in the project. | Work products |
Output Software Requirements Specification (SRS)
| Entry criteria | A requirements analyst has a vision and scope document for a project and has identified a set of users, stakeholders, and other people who will participate in the elicitation process. | Basic course of events | Elicitation: The script begins with the elicitation process. The requirements analyst works with users, stakeholders, and other people to elicit their needs and any known requirements. If there are outstanding issues or SRS defects, the analyst resolves them during the elicitation activities. Documentation: The requirements analyst creates or updates the draft of the SRS to reflect the data elicited in Step 1. Verification: A team of reviewers performs a review of the SRS draft. In the first iteration, a small number of reviewers perform a deskcheck of the draft. Later reviews will include more people, and may be inspections instead of deskchecks. Walkthroughs should be conducted for non-technical people who still need to understand the contents of the SRS. The last iteration must be an inspection.
| Exit criteria | The script ends after the draft was inspected in Step 3 and no defects were found. If defects were found or there was only a deskcheck performed in Step 3, then the script returns to step 1 for the next iteration. |
The goal of the SRS development script is to remove as many defects as possible from the SRS. Many people have trouble figuring out what constitutes a defect. In this case, a defect is any planned software behavior a project team member, user, stakeholder, or decision-maker does not agree with. This means that defects could be caused by any number of problems: Somebody does not believe that the planned behavior will satisfy the users' or stakeholders' needs. Somebody believes that those needs may be better satisfied with different behavior. An inspector does not understand what's written or feels that it is ambiguous or confusing. A project team member does not believe that the behavior can be implemented as written. Two or more requirements contradict each otheran implementation that satisfies one cannot satisfy the others.
If there is a requirement in the SRS that has one of these problems, it must be identified and fixed so that everyone agrees on everything in the document. There will almost certainly be defects that slip throughno inspection team is perfectand each of these will cost much more time to fix after it has been designed, coded, and tested than it would have if it had been caught using the SRS development script. The goal is to find as many defects as possible, in order to reduce the amount of time that the team must spend later on in the project undoing the few that slipped past. One of the most common mistakes in software engineering is to shortchange the SRS. A good project manager knows that the fastest way to finish a project is to take the time up front to get the requirements right. For many managers, however, cutting the requirements short sometimes seems tempting. They are impatient to have the programmers begin working on something concrete that they can use, and do not necessarily see the value of planning the behavior of the software before it is built. But skipping the software requirements activities will always come back to damage the project later. Any defects in the SRS will get magnified in later work products. If a defect is left in the SRS and not caught until testing, that defect will be designed into the software. If the defect is still not caught in the design phase, then code will be built to implement that design, and a test plan will be created and executed that verifies that behavior is accurately reflected in the final build. When that defect is eventually discovered by a user, fixing it will require an enormous amount of effort from the entire project team. This is why it is worth spending time doing extra iterations of reviews at the outset of the projectit's much more efficient to build the software right the first time than it is to go back and fix it later. The best way to prevent defects is through iteration. This is why the SRS development script calls for repeated reviews of the SRS. It may seem to the project team that they are sitting through redundant deskchecks, walkthroughs, and inspections of a single SRS. It is sometimes tempting to cut this process short and declare that the SRS is "good enough." The project manager needs to resist this urge. When the SRS goes through what some people might perceive as "yet another iteration," it's because somebody found a defect in it that needs to be fixed. If this defect is not fixed now, the effort required to fix it later will dwarf the effort required to do another review of the SRS. There is a risk that when nontechnical people read the SRS draft, they will fail to understand what is written in it and simply agree to whatever is written down. This often happens in an organization in which software requirements have never been used before. To address this problem, the project manager should work to help everyone understand why it is so important that they take the time to read and understand each SRS draft. This often requires sitting down with each person to make sure he really read and understood the document. Even if that seems time-consuming and patronizing, it's better than losing an enormous portion of the project's effort because the team is busy fixing defects that could have been caught in the first place. If users and stakeholders are used to playing with intermediate builds and vetoing software features that they don't like, they may object to sitting through a walkthrough meeting rather than waiting until the programmers produce something. However, that's a very costly way to build software. Words on a page are much easier to change than functions and objects in source code. A defect that only takes a few minutes to fix in a draft of an SRS can require days, weeks, or months of the most irritating sort of programming to repair after it's been coded. This is why it's in the project team's best interest to catch the defects as early as possible. Another problem is that some people may not read repeated drafts; after seeing the first few drafts, they may start to ignore later revisions. One way to reduce the risk of this happening is to keep the initial iterations' review teams very small, and only expand them when the draft is close to completion. People who are not used to reading technical documentation are much more likely to read a single draft than they are to read a half-dozen of them. But in the last iterations, it still may be difficult to get nontechnical people to work their way through a technical document. This is where a walkthrough can be a useful tool to ensure that everyone understands the document. (See Chapter 5 for more information on walkthroughs.) 6.3.3. Requirements Differ from Design Many people have trouble understanding the difference between scope (which demonstrates the needs of the organization), the requirements (which describe the behavior of the software to be implemented), and design (which shows how the behavior will be implemented). It is hard for them to describe the behavior of a piece of software without talking about windows, forms, buttons, checkboxes, clicking, dragging, etc. The difference between scope, requirements, and design is a very important distinction that the entire project team should be familiar with. Table 6-13 shows several examples that illustrate the difference between the user needs that might appear in a vision and scope document, the behavior that might appear in an SRS, and the design that might appear in a design specification or code comments. As a general rule, unless the requirements analyst specifically intends to constrain the designers and programmers, design elements should be left out of the SRS. Table 6-13. Examples to illustrate the difference between needs, behavior, and designNeeds | Behavior | Design |
|---|
The users need to be able to easily search and replace text. | A user indicates that search-and-replace is needed. The software responds by prompting for a search term and replacement text. The user enters the text and indicates that the software is to do a case-sensitive search to replace all occurrences. | A user selects "Search" from the "Edit" menu. The software pops up a window with a text box for a search term, a text box for the replacement text, a checkbox for case-sensitivity (defaulted to unchecked), and a button labeled "Replace All." The user enters the search term and replacement text into the appropriate text boxes, checks the checkbox, and clicks the button to initiate the search. | A user composing email needs to be able to look up contacts in an address book. | A user entering the header information in an email being composed indicates that the current header field should be populated using the address book. The software responds by displaying a list of contacts, including full name and email address. The user specifies one. The software responds by returning to the email and adding the specified name and address to the header field. | The user has the "compose email" window active, selects one of the text boxes that contains the To: or From: header, and clicks the address book button next to the text box. The software responds by popping up a modal dialog that contains the address book entries in a listbox. The user scrolls down to the email address to be added to the field, clicks on the name, and clicks the "Add" button. The software closes the address book window and adds the name to the field that was being edited. | A user needs to search the Internet for web pages that contain certain words. | A user indicates a search term to the search engine. The software responds by displaying a list of pages that match the criteria. The list is limited to 100 results. The user may indicate that the next 100 results are to be displayed, in which case the system displays those results instead. | A user navigates to the home page of the search engine. The software responds by displaying a text box and a button labeled "Search." The user enters the search term into the text box and clicks the button. The software responds by displaying a page with 100 results, with 1 link per result. At the bottom of the page is a link labeled "Next 100 hits." If the user clicks on that link, the search engine displays the next 100 hits, with a link labeled "Next 100 hits" and another labeled "Previous 100 hits." |
6.3.4. SRS Inspection Checklist The SRS development script specifies that its last iteration must include an inspection of the SRS. The following checklist can serve as a guide to SRS inspectors. It is divided into sections that provide criteria for evaluating the SRS document in general, the use cases, and the requirements. The following checklist items apply to the entire SRS.
Document completeness Does the document meet all established templates and standards? Is the document complete? Is there any information that should be included, but is not? Is there any information that should be removed? Are all of the references valid?
Document feasibility Can the project as specified be accomplished within known cost and schedule constraints?
Document modifiability Is the document structured so that any changes can be made easily, completely, and consistently?
Document feasibility Can every element of the SRS be implemented with the available resources and tools?
The following checklist items apply to the use cases.
Use case clarity Does each use case have a clear flow of events? Is every action that the system takes performed in response to an action by the user or to a specific event? Has unnecessary duplication been removed using generalization and/or references? Is each use case uniquely identified with a name and a number?
Use case completeness Are all of the steps in each use case necessary? Are there any steps that are missing? Are all alternative paths and exceptions accounted for?
Use case level of detail Does any use case contain details (such as specific calculations, constraints, or other internals that would not directly be observed by the user) that should really be part of the functional requirements instead? Does any use case unintentionally constrain the design?
Use case testability Is each use case testable?
The following checklist items apply to the functional and nonfunctional requirements.
Requirement clarity Is each requirement clear, unambiguous, and readable? Is each requirement uniquely identified with a name and a number?
Requirement completeness Is each requirement complete? Are there requirements that are missing?
Requirement level of detail Do any requirements unintentionally constrain the design?
Requirement consistency Are the requirements consistent? Does any requirement contradict another requirement? Are all data structures, calculations, and functions named and used consistently?
Requirement functionality Is every requirement correct? Are all inputs and outputs clearly specified?
Requirement performance Are all nonfunctional requirements that constrain performance (speed, resource utilization, etc.) clearly and quantitatively defined?
Requirement testability Is each requirement testable?
Note: More information on SRS development can be found in Managing Software Requirements: A Use Case Approach by Dean Leffingwell and Don Widrig (Addison Wesley, 2003) and Software Requirements by Karl Wiegers (Addison Wesley, 2003).
|
