Guideline: Requirement Pitfalls |
This guideline provides a description of common pitfalls to avoid in defining and writing requirements. In some cases these are the inverse of the guidelines for writing good requirements, however, by showing examples of what NOT to do can help explain better.
Relationships
Related Elements | Detail Requirements Find and Outline Requirements
Main Description
Here is a list of common pitfalls to avoid in defining and writing requirements. For more information, please refer to [TEL06]. Avoid ambiguity Avoidance of ambiguity is one of the subtlest and most difficult issues in writing requirements. Try to write as clearly and explicitly as possible. Remember if this is carried too far, the text becomes dull and unreadable—and therefore cannot be improved by other people. Although this guideline emphasizes structured written expression of requirements, informal text, diagrams, conversations, and phone calls are excellent ways of removing ambiguity. Dangerous ambiguities can be caused by the word "or", and also by many more subtle errors. Example: The same subsystem shall also be able to generate a visible or audible caution/warning signal for the attention of the co-pilot or navigator. Which subsystem? Is the signal to be visible, audible, or both? Is it both caution and warning, just caution, or just warning? Is it for both the co-pilot and the navigator, or just one of them? If just one of them, which one and under what conditions? Don't make multiple requirements Requirements which contain conjunctions (words that join sentences together) are dangerous. Problems arise when readers try to puzzle out which part applies, especially if the different clauses seem to conflict, or if the individual parts apply separately. Dangerous conjunctions include "and", "or", "with", "also". Example: The battery low warning lamp shall light up when the voltage drops below 3.6 Volts, and the current workspace or input data shall be saved. Never build in let-out or escape clauses Requirements which contain let-outs or escapes are dangerous. They look as though they are asking for something definite, but at the last moment they back down and allow for other options. Problems arise when the requirements are to be tested, and someone has to decide what (if anything) could prove the requirement was not met. Dangerous let-outs include: "if", "when", "but", "except", "unless", "although". Examples: The forward passenger doors shall open automatically when the aircraft has halted, except when the rear ramp is deployed. The fire alarm shall always be sounded when smoke is detected, unless the alarm is being tested or the engineer has suppressed the alarm. (This is a truly dangerous requirement!) Don't ramble Long rambling sentences, especially when combined with arcane language, references to unreachable documents, and other defects of writing, quickly lead to confusion and error. Example: Provided that the designated input signals from the specified devices are received in the correct order where the system is able to differentiate the designators, the output signal shall comply with the required framework of section 3.1.5 to indicate the desired input state. Refrain from designing the system Requirements should specify the design envelope without unneccessary constraints on a specific design. If we supply too much detail we start to design the system. Going too far is tempting for designers, especially when they come to their favorite bits. Danger signs include names of components, materials, software objects/procedures, and database fields. Example: The antenna shall be capable of receiving FM signals, using a copper core with nylon covering and a waterproof hardened rubber shield. Specifying design rather than actual need increases the cost of systems by placing needless constraints on development and manufacture. Often knowing why is much better than knowing what. Avoid mixing different kinds of requirements The user requirements form a complete model of what users want. They need to be organized coherently to show gaps and overlaps. The same applies to system requirements—form a complete functional model of the proposed system. A quick road to confusion is to mix up requirements for users, systems, and how the system should be designed, tested, or installed. Danger signs are any references to system, design, testing, or installation. Example: The user shall be able to view the currently selected channel number which shall be displayed in 14pt Swiss type on an LCD panel tested to Federal Regulation Standard 567-89 and mounted with shockproof rubber washers. Do not speculate Requirements are part of a contract between customer and developer. There is no room for wish lists—general terms about things that somebody probably wants. Danger signs include vagueness about which type of user is speaking, and generalization words: "usually", "generally", "often", "normally", "typically". Example: Users normally require early indication of intrusion into the system. Do not play on ambiguous requirements Some constructions (such as the use of or and unless in requirements) allow different groups of readers to understand different things from the same wording. Developers could use this technique deliberately, so as to postpone, until too late, any possibility of the customer's asking for what was truly wanted. This is dangerous and could easily backfire. The only approach that works is for developers to make requirements as clear as possible, and for all stakeholders to co-operate. In the long run, project success is in everybody's interest. Do not use vague undefinable terms Many words used informally to indicate system quality are too vague for use in requirements. Vague terms include: "user-friendly", "versatile", "flexible", "approximately", "as possible". Requirements using these terms are unverifiable because there is no definite test to show whether the system has the indicated property. Examples: The print dialog shall be versatile and user-friendly. The OK status indicator lamp shall be illuminated as soon as possible after the system self-check is completed. Do not express possibilities Suggestions that are not explicitly stated as requirements are invariably ignored by developers. Possible options are indicated with terms such as: "may", "might", "should", "ought", "could", "perhaps", "probably". Example: The reception subsystem probably ought to be powerful enough to receive a signal inside a steel-framed building. Avoid wishful thinking Engineering is a real-world activity. No system or component is perfect. Wishful thinking means asking for the impossible. Wishful terms include: "100% reliable"; "Safe"; "Handle all unexpected failures"; "Please all users"; "Run on all platforms"; "Never fail"; "Upgradeable to all future situations". Examples: The gearbox shall be 100% safe in normal operation. The network shall handle all unexpected errors without crashing.
This program and the accompanying materials are made available under the Eclipse Public License v1.0 which accompanies this distribution. View copyright information here: OpenUP Copyright