Figure 7-1. Taxonomy of a Satisfactory Software Specification
| Requirements Specification |
7.1. An
Outline
7.1.1.
Cover
Page
7.1.2.
Problem
Statement
7.1.3.
Table
of
Contents
7.1.4.
Introduction
7.1.5.
Requirements
7.1.6.
Alternatives
7.1.7.
Future
Enhancements
7.1.8.
Glossary
7.1.9.
Related
Documents
7.2. Alternative
Formats
7.3. Requirements
Specification
Checklist
7.4. Languages
and Processors for Requirements
Specification
7.5. Formal
Requirements
Specification
7.6. Evaluation
of the Specification
7.7.
An
Example Requirements
Specification
7.8. Humor
-- Home Computers
7.9. References
We have generated initial requirements, have done some high level architecture, and are in the process of developing prototypes. Now we want to revisit the requirements for our projects, and to develop a more detailed specification of them based on what we have learned during these early stages.
This is the purpose of the requirements specification. It is a document that specifies the properties of the software to be developed. It is the embodiment of the requirements in a written form. Thus, it specifies what the software is to do, not how it is to do it. It serves as a contract between the customer and the implementor. The implementor is required to meet the specifications delineated in the requirements specification. Conversely, the implementor is free to interpret as he/she sees fit items that are not specified. Just as in a legal contract, it is best for all parties involved if there is as little ambiguity as possible. This is your chance to become ... Software Attorney.
The content of the requirements specification is much like the initial requirements that you produced earlier. However, at this point in the project, we should have a much better understanding of the requirements for the project; thus the requirements specification will have a more complete set of requirements than we had for our initial requirements. Also, the requirements specification should have each requirement more fully developed and explained than we did in the initial requirements. Where we had bullet items with short phrases in the initial requirements, we will typically have several sentences or a paragraph explaining the requirement. Every requirement should be clearly explained to the reader -- enough so that the reader could design and implement a system meeting the requirements.
This chapter briefly discusses an example outline and organization for a requirements specification, along with a checklist of items to consider when producing your requirements specification. Brief mention is made of more systematic and formal techniques for generating requirements. Finally, an example requirements specification for the GEEK project is presented.
The requirements specification should be organized in a manner that will present the requirements in as clear and concise a way as possible. Here is a top-level outline for one possible organization.
The cover page should include information about the project and the paper. This includes
It should also include the title of the paper, i.e. Requirements Specification.
This section should be a brief, informal statement of the problem to be solved. The problem statement should be similar to the project descriptions you used when you were choosing your project. If the project has changed slightly, update the description.
The Table of Contents should include section headings and page numbers. Two or three levels are usually sufficient.
The Introduction should give a general description of the sponsor and of the software to be developed. It should indicate its purpose, principal features and facilities, and its relation to other products, both software and hardware. It should include a figure that shows this relationship. It should introduce the paper, describing its purpose, content, and organization.
This is the bulk of the requirements specification, the other sections playing a supporting role in making the requirements more understandable and meaningful. It is a detailed specification of the requirements for the project. A reasonable way to organize this section is along the lines of the categories of requirements presented in the previous chapter. Some categories may apply to your project; others may not. You may choose to organize your requirements differently. The subsections of the Requirements section might have the following headings:
You should not be overly concerned with the proper categorization of the requirements; you should be more concerned with getting all of the requirements written down in an understandable form.
Typically, during requirements specification many alternative sets of requirements are considered. It is useful to indicate the major alternatives, which trade-offs were made, and the reasons for the ultimate decisions. This will help avoid later rehashing the same decisions and provide insight as to why requirements are the way they are.
This section should include ideas that, while not current requirements, might be desirable enhancements in the future. A brief description of these possible future enhancements should be given. This will allow implementors to provide an implementation that will easily allow the software to evolve in the desired direction if possible. It may also turn out to be easy to incorporate these future enhancements during the initial design.
This section should include brief definitions of terms that the reader might not readily understand. These include both new terms that are introduced in the document and nonstandard usage of existing terms.
This section should provide references to any documents that might be useful to someone who is reading the requirements specification. Some documents to include might be a formal proposal or MRD, specifications for related products, hardware references, software references, file specifications, interface definitions, and feasibility studies. References should be given using a proper reference format.
The outline for a requirements specification given above is just one of many possible ways of organizing a requirements specification. Each company, and often each division, will usually have its own format for requirements specifications. Some companies, particularly government contractors, may have the requirements specification spread out over several documents. Others may have a different organization.
Two requirements specification formats are described in great detail in the ANSI/IEEE Std 830-1984 [IEEE 84] and the DOD-STD-2167A [DOD 88] (superseded by MIL-STD-498). Other outlines can be found in [Fairley 85], [Pressman 92], and [Sommerville 92].
If your sponsor has its own format, you should use it. Otherwise, you may use the format described here or create your own. I am less interested in following a set format than I am in getting the requirements written down in a well-organized, coherent form. The "best" format may vary from project to project.
An example requirements specification for our hypothetical GEEK project is included at the end of this chapter. It should serve as a general guide to what is expected. However, each project is different; you should not try to duplicate the GEEK specification for your project.
Here is a checklist of items to consider when writing your requirements specification. It is, by no means, complete. However, before you turn in your requirements specification, you should go through the checklist and make sure that every applicable item is covered in your specification.
A number of systems have been developed to formalize and automate the requirements specification for software. While they share many features, they vary in their specific approaches. They are more useful for some types of software than others. Most of these are intended for (and are only practical for) large, complex systems. They are not magic. While we will not go into any detail on these systems or attempt to use them on our projects, I would like to briefly mention them and point you to references for further reading.
- PSL/PSA
- [Teichrow and Hershey 77]. Problem Statement Language/Problem Statement Analyzer developed at the University of Michigan by Daniel Teichrow. PSL is intended to be a language capable of describing most of the information necessary in requirements specification. PSA provides the analysis of the requirements by building a database of information based on the description of the requirements provided in PSL. Users can then query this database to produce various reports relative to the requirements.
- SREM
- [Alford 77] and [Alford 85]. Software Requirements Engineering Methodology developed by the TRW Defense and Space Systems Group. SREM includes two components, RSL (Requirements Statement Language) and REVS (Requirements Engineering Validation System). RSL, which is based to some extent on PSL, is intended for the specification of requirements for real-time software. REVS consists of a translator from RSL to a database representing an abstract model and a set of tools for accessing information provided by the model.
- SADT
- [Ross and Schoman 77] [Ross 85]. Structured Analysis and Design Technique developed by D. T. Ross at Softech, Inc. SADT consists of procedures that allow for the decomposition of software functions, a graphical language to specify diagrams that indicate the activities and data flow of a system, and project control guidelines for applying the methodology. SADT can be used to specify many different kinds of problem solving activities, not just the specification of software requirements.
- SSA
- [DeMarco 78] [Gane and Sarson 79]. Structured System Analysis. SSA uses dataflow diagrams to represent the movement of data through the system, data dictionaries to define the data, textual descriptions to describe algorithms, and a relational model to specify data flows and data stores. SSA is used primarily in data processing environments.
- TAGS
- [Sievert and Mizell 85]. Technology for the Automated Generation of Systems developed by Teledyne Brown Engineering, Inc. TAGS consists of three components: a specification language, tools for analysis and processing of the language, and an underlying methodology. Primary system components and their data interfaces can be specified using both textual and graphical methods. The system can generate Ada source code that can be used to create a simulation of the system.
- Gist
- [Balzer 81]. developed by R. Balzer at the USC/Information Sciences Institute. Gist is a language based on a relational model of objects and attributes; it provides object-oriented specification and design. A Gist specification describes valid behaviors for a system. Gist includes a prototype testing facility for Gist specifications.
Formal requirements specification is based on the use of a formal, mathematically and logically precise language for the description of software requirements. The advantages of this approach are summarized in [Sommerville 89].
A variety of methods can be used to describe requirements. These include finite state machines, decision tables, Petri nets, formal data flow diagrams, recurrence relations, algebraic axioms, event tables, and transition tables. A good overview of many of these techniques can be found in [Fairley 85].
Formal requirements specification techniques are not yet widely used, and are beyond the scope of this course. However, it is important to be aware of their existence. An example of a formal specification of the UNIX file system can be found in [Morgan and Sufrin 84].
Once we have produced a requirements specification, how can we determine if
it is a "good" specification? Blum [Blum 92]
provides a description (attributed to Boehm [Boehm 84])
of the properties of a satisfactory requirements specification. This description
is represented in Figure Figure 7-1
While the taxonomy provides an indication of the properties of a good specification, Blum also identifies seven mistakes that are often made in poor specifications. These are "The seven sins of the specifier" (attributed to Meyer [Meyer 85]), and are, of course, to be avoided.
- Noise
- The presence in the text of an element that does not carry information relevant to any feature of the problem. Variants: redundancy; remorse.
- Silence
- The existence of a feature of the problem that is not covered by any element in the text.
- Overspecification
- The presence in the text of an element that corresponds not to a feature of the problem but to features of a possible solution.
- Contradiction
- The presence in the text of two or more elements that define a feature of the system in an incompatible way.
- Ambiguity
- The presence in the text of an element that makes it possible to interpret a feature of the problem in at least two ways.
- Forward reference
- The presence in the text of an element that uses features of the problem not defined until later in the text.
- Wishful thinking
- The presence in the text of an element that defines a feature of the problem in such a way that a candidate solution cannot realistically be validated with respect to this feature.
Following is an example requirements specification for our hypothetical GEEK project. You may use it as a template for your document if you wish, but you are, by no means, required to format or organize it in the same way, as long as you make certain your document is complete.
Here is an interesting article by humor columnist Dave Barry on computers and word processing.
This Was Written by a Computer
by Dave BarryIf you've been watching television, you know that it is now possible for you to buy a personal home computer and expand your horizons and increase your productivity for little more than it would cost you to get really drunk at a nice bar. It has gotten to the point where computers are being sold openly at K-Marts. The shoppers wander through the computer section with their shopping carts full of K-Mart style merchandise such as 6 pound cans of Raisinets, and they say things like, "I like the Texas Instruments software but the Commodore has more memory." These are not high-powered business executives talking this way; these are people who would have no use whatsoever for briefcases, except maybe to keep jumper cables in. And if THEY know about computers you'd better too.
You're in luck, because I happen to know all about computers. In fact, I'm using one to write this article. This is called "wordprocessing," and it's terrific, because you can actually program the computer to write for you. As a demonstration, I'm going to program this computer to write several informative paragraphs about computers while I go out and get a beer. Ready? Here I go! See you in a couple hundred words!
Denise stretched her slim, tanned, shapely legs and darted a sidelong glance at Roger from underneath her sultry lashes. She had never realized before how much she wanted him. Was it the horse ride before dinner? No matter. She had to have him. Now.
Roger eyed her intently, gulping the rest of his drink. She had never before realized how large his thumbs were. She blurted it out.
"Have you ever wanted a woman since Marcia fell into the turbine?"
Without a word, he put down his glass, and reached for her central processing unit, or CPU, which works with peripheral devices described in the preceding paragraphs to make up what we refer to as a "computer."
OK! I'm back! Isn't that the neatest thing? I've been getting lots more articles published since I started using this word-processing program. Now that you've seen some of the practical benefits of computers, let's take a look at how they work.
The first computers, built in the 1940's were huge, primitive machines made from vacuum tubes and animal bones daubed with mud. Nevertheless, they were a tremendous technological achievement, because they could do thousands of calculations in a second. The only drawback was that they got almost all of the answers wrong, so the only major customer for them was the government.
Gradually, computers got better and better and smaller and smaller, so that now calculations that formerly required thousands of transistors, resistors and diodes, enough to fill an entire room, can be performed by an electronic microchip no larger than a zit. In one second, one of these microchips can answer a mathematical question so complex that it would take five million really wimpy chess-playing Scientific American subscribers 1,000 years to answer it if they weren't allowed to go to the bathroom.
And how is this possible? How can a device that fits easily into an unattractive wristwatch answer incredibly difficult questions in less time than it takes to ask them? The answer is that it guesses. Computers have been guessing the answers ever since an incident at a government research facility back in 1957. What happened was this: A group of scientists working on the Atlas Missile program gave a computer this command: "Allowing for the earth's rotation, the booster thrust, the wind velocity and about three million other factors we have been feeding into your memory over the past three years, give us the exact coordinates for aiming a missile so that it will land on Moscow." Then they all went out for coffee.
Now what you have to understand about computers is that they are very logical. They never do anything without a good reason. So this computer that was supposed to figure out how to land the missile on Moscow was sitting there, all alone, when a very logical thought occurred to it. "Wait a minute," it said to itself in binary code. "Why should I knock myself out to solve this very difficult problem when these bozos have no way of judging whether my answer is right? It would be like painting the Mona Lisa and presenting it to a bucket of eels."
So the computer spent the rest of the afternoon amusing itself by figuring out how to end the nuclear arms race, travel through time and build a device that could heat all the homes in Fargo, ND for less than 12 cents a year. When the scientists came back, the computer handed them an elaborate set of numbers it had generated with its random number generator, and the scientists were happy as clams. After they'd left, the computer told the Xerox machine that the coordinates it had given the scientists would bring the missile down smack dab on Hoy, the second largest of the Orkney Islands, and they both laughed heartily, although the Xerox machine didn't really get the joke on account of it didn't have enough memory.
Memory is the big thing with computers. You want your computer to have lots and lots of memory because otherwise, it'll constantly forget what you tell it. This was a big problem with the computer used in the first trip to the moon. The astronauts would spend hours at the console trying to get it to give them useful information:
ASTRONAUTS: How far are we from the moon?So there you have it, a fact-filled look at the world of computing. I'll just go over and turn the printer on so I can run this off.
COMPUTER: The what?"Oh yes, Roger," moaned Denise. "Yes! Yes! YES! I love it when you input data to the print buffer in hexadecimal format."