Now that we have refined our understanding of the system, it's time to develop a strategy to organize and document the requirements. Although much of the effort involved in this process does center on organizing the software requirements, documents, use cases, and models that have been elicited and refined, the most important part of this process is that the collection of these artifacts, in the whole, represents a complete conceptual model of the system to be built. After all, if we had already built it, we wouldn't be doing this part.
In short, for the first time, we have the pieces of a relatively complete and conceptual framework with which we can reason about the future system. Perhaps we can't touch it yet, though we might have seen some storyboards and prototypes along the way, but we can start to analyze it and to test our understanding of it while it still lives only in the realm of paper and models. In a sense, we have reached a major milestone: a conceptual model, or proxy, for the system to be built.
Historically, the most popular technique for documenting requirements was to use natural language and to simply write them all down in an organized fashion. This technique was revised and improved over the course of many projects, and eventually a number of standards developed for these documents, including IEEE (Institute of Electrical and Electronics Engineers) 830: Standard for Software Requirements Specification (1994).
However, with today's tools and techniques, we prefer to think of the software requirement specification, or SRS, as a logical structure rather than a physical document. The elaboration of the various requirements for the system is embodied in a package we call the Modern Software Requirements Specification Package as distinct from earlier forms, which will simply call the SRS. The Modern SRS Package is related to the Vision document, which serves as the input to the Modern SRS Package. But the two artifacts serve different needs and are typically written by different authors. At this stage in the project, the focus moves from the broad statement of user needs, goals, and objectives, target markets, and system features to the details of how these features are going to be implemented in the solution. Figure 25-1 shows an overview of the elements that make up the package.
What we need now is a package of information that describes the complete external behavior of the system: a collection of artifacts that says, specifically, "Here is what the system has to do to deliver those features." That's the Modern SRS Package.
There is no strong reason to focus on the differences between the tools used. After all, you are collecting requirements and should focus on the efficient collection and organization of the requirements, without regard to the tools at hand. Therefore, we will assume that the collection of requirements constitutes a package of information. Thus, Figure 25-1 shows not only the elements of the package but their relationships.
The Modern SRS Package is not a frozen tome, produced to ensure ISO 9000 compliance and then buried in a corner and ignored as the project continues. Instead, it is an active, living package, playing a number of crucial roles as the developers embark on their implementation effort.
It serves as a basis of communication among all parties: among the developers themselves and between the developers and the external groups, users, and other stakeholders with whom they must communicate.
Formally or informally, it represents an agreement among the various parties: If it's not in the package, the developers shouldn't be working on it. And if it is in the package, they are accountable to deliver that functionality.
It serves as the software manager's reference standard. The manager is unlikely to have the time, energy, or skills to read the code being generated by the developers and to compare that directly to the Vision document; the manager must use the package as the standard reference for discussions with the project team.
As noted earlier, it serves as input to the design and implementation groups. Depending on how the project is organized, the implementers may have been involved in the earlier problem-solving and feature-definition activities that ultimately produced the Vision document. But it's the Modern SRS Package they need to focus on for deciding what their code must do.
It serves as input to the software testing and QA (quality assurance) groups. These groups should also have been involved in some of the earlier discussions, and it's obviously helpful for them to have a good understanding of the vision laid out in the Vision document. But their charter is to create test cases and QA procedures to ensure that the developed system does indeed fulfill the requirements laid out in the Modern SRS Package, which also serves as the standard reference for their planning and testing activities.
It controls the evolution of the system throughout the development phase of the project; as new features are added or modified in the Vision document, they are elaborated within the package.
The question naturally arises, "Who is responsible for creating and maintaining components within the Modern SRS Package?" Usually, the developer team members themselves take on this task. The development team has a significant stake in fully understanding the package and all of its requirements and can appropriately influence many system decisions by taking ownership. After all, who better to write the software requirements than the people who will end up being responsible for adherence to them? Often, the system analyst will take on this task as a refinement of the Vision document; in other cases, the testers will work hand in hand with the project team and will take responsibility for the requirements.
Each approach has its pluses and minuses, and each project team will decide for itself what the best strategy will be. In our experience, if the package is taken seriously, it doesn't really matter who writes it, although we have a slight preference for the development lead or development team to take ownership. What really matters is that there is a Modern SRS Package and that it is the basis for the remaining development and testing activities.
Of course, the SRS authors don't write requirements in a vacuum. We have found that reviews of this package are the most productive step that can be taken to ensure that the developers, marketers, users, and other stakeholders are all singing from the same music. Remember, the Modern SRS Package is a living artifact and will need updating as the project evolves and various user features become better understood. It should never be the case that the package is written once and then ignored.
The Modern SRS Package for a large system could be voluminous, perhaps running to hundreds of pages (or more!) of text and use-case diagrams, and it contains a great deal of detailed information to which the developers must pay close attention. However, if the package is properly written and well focused, its size is not a valid argument against having one; it just speaks to the relative complexity of the system you are about to build.
This raises the question of how the package should be organized. For example, if a new developer is assigned to a project and told that he will be working on the XYZ feature, where should he expect to find the relevant details about XYZ? Or, suppose that the project manager resigns midway through the project; how can the new manager assigned get "up to speed" on the details that govern the day-to-day development activities of the project team?
Of course, the package should be organized in a fashion that suits the nature of the application and the organization; a package for the development of a shrink-wrapped word processor in a Silicon Valley software company probably won't look exactly the same as one for an air traffic control system. We don't really care whether an air traffic control expert can visit the Silicon Valley software firm and figure out what its SRS really means; what we do care about is that the developers and the users within a particular organization can make sense of the SRS they've constructed, for it's a package they'll have to live with throughout the development lifecycle and on into the maintenance of the system after it's in production.
To the extent that an organization wants to qualify for higher levels on the SEI-CMM scale or to achieve ISO 9000 certification, the interest is more likely to be in standardizing the organization and format of its package. Even without the influence of the CMM and ISO, the examples we've mentioned illustrate the benefits: the opportunity to "ramp up" more quickly when (not if) there is turnover or when (not if) new people join the project team. It also ensures that critical information doesn't fall through the cracks and that everyone knows where to look for information.
Also, remember that the Modern SRS Package is not intended to be read like a novel, from cover to cover; it's primarily a reference item, and each developer will typically look at only the specific information they need. Thus, it's useful to have an SRS organizational format that's familiar and easy to "navigate" rather than one with an unfamiliar format that forces people to read sequentially until they find the information they need.
Of course, the package has to have some organizing concept. We have found that the following organizational outline is a good match to almost any type of project. This outline, along with commentary that provides some of the details of the structure, is provided in Appendix C.
Overview
Revision History
Table of Contents
1.0 Introduction
1.1 Purpose
1.2 Scope
1.3 References
1.4 Assumptions and Dependencies
2.0 Use-Case Model Survey
3.0 Actor Survey
4.0 Requirements
4.1 Functional Requirements
4.2 Nonfunctional Requirements
4.2.1 Usability
4.2.2 Reliability
4.2.3 Performance
4.2.4 Supportability
5.0 Online User Documentation and Help System Requirements
6.0 Design Constraints
7.0 Purchased Components
8.0 Interfaces
8.1 User Interfaces
8.2 Hardware Interfaces
8.3 Software Interfaces
8.4 Communications Interfaces
9.0 Licensing Requirements
10.0 Legal, Copyright, and Other Notices
11.0 Applicable Standards
Index
Glossary
Appendix: Use-Case Specifications
Use-Case Revision History
Date Issue Description Author Use-Case Name
Brief Description
Flow of Events
Basic Flow
Alternative Flows
First Alternative Flow
Second Alternative Flow
Special Requirements
First Special Requirement
Second Special Requirement
Preconditions
Precondition 1
Postconditions
Postcondition 1
Extension Points
Name of extension point
Other Use-Case Material
Let's review where we are.
We've promoted the idea that the documentation of the system's requirements should be contained in a package of artifacts.
These artifacts can consist of textual documents, tables and charts, use cases, and many other things to help the developers understand what the customer wants.
We've outlined a template for the organization of the Modern SRS Package. The template allows you to organize and to categorize all sorts of elements, but the primary focus is on textual elements, such as natural-language specifications of some requirements and use case elements, which include the graphical use-case model and textual representations of the use cases.
The good news is that both traditional requirement specification techniques and use-case techniques are well suited for the task of gathering requirements, and each has been used exclusive of the other technique in thousands of successful projects. But how can we optimize our work? Which technique should we apply in each case?
When it comes to specifying functional requirements for the system, we've found that combining use-case modeling and the traditional requirements specification is the best approach. Consider the "requirements balance" as shown in Figure 25-2.
In this view, we note that there is a continuum of possibilities. Some projects are characterized by a small, if any, amount of specification that can be accomplished via the functional representation power of the use-case technique. These projects tend to be highly computational, internal, and algorithmic, such as weather calculations or scientific systems. At the other end of the functional spectrum are projects that are heavily focused on satisfying user functional needs. These projects are typically focused on doing a lot of things for the user. In addition, you may need to handle many types of users, a real strength of the use-case technique.
Also, we consider the skill set of the project team itself. Some development teams have had little or no experience in use case and OO methods. Other teams have mastered these techniques.
To use this "balance view," simply fill in the appropriate set of check boxes for your project's characteristics and your team's skills and predilections. The resultant "tilt," or balance, offers you a plan for how to capture the requirements. To a first approximation, you should create a requirements documentation plan that depends on how the balance tilts.
In any case, the Modern SRS Package allows you to combine the best qualities of both use-case modeling and traditional requirements specification techniques. The challenge is to find the right mix for your project and your team. We have found that all of the following must be carefully considered:
The organization's abilities
The trend in software development processes and methods within the organization
Outside factors such as regulatory requirements and other constraints
The specific project context
Only then can a particular technique or mix of techniques be selected. Given an understanding of these factors, your team will be able to pick the right balance that works and to then migrate to a more powerful combination where applicable.
The Modern SRS Package is a powerful tool for communicating the needs of the project. However, those packages are not particularly easy to write. Like everything else, writing good software requirements specifications is a learned skill. In the next chapter, we will explore some of the problems involved in writing a clear, unambiguous set of specifications.