Guideline: Requirement Pitfalls
This guideline describes 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 makes the explanation of what TO DO clearer.
Relationships
Related Elements
Main Description

Explanations and examples follow for each of the following common pitfalls to avoid in defining and writing requirements (for more information, see [TEL06]):

  • Avoid ambiguity
  • Don't make multiple requirements
  • Never use let-out or escape words
  • Don't ramble
  • Resist designing the system
  • Avoid mixing different kinds of requirements
  • Do not speculate
  • Do not use vague, undefined terms
  • Do not express possibilities
  • Avoid wishful thinking

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. Be specific. Remember, though, that if you carry this too far, the text becomes dull and unreadable, which makes it difficult for other people to review. Although this guideline emphasizes structured, written expression of requirements, informal text, diagrams, conversations, and phone calls are excellent ways of removing ambiguity.

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.

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 independent clauses together) are dangerous. Problems arise when readers try to figure out which part applies, especially if the different clauses seem to conflict, or if the individual parts apply separately. Multiple requirements also make verification more complex.

Dangerous conjunctions include: and, or, but

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.

Should the battery low warning lamp light up when the voltage drops and the workspace is saved? Should the battery low warning lamp light up and the workspace be saved when the voltage drops?

Never use let-out or escape words

Requirements that include options or exceptions are dangerous. They seem to ask 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 met.

Dangerous words that imply exceptions 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.

The latter sentence 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.

Resist designing the system

Requirements should specify the design envelope without unnecessary 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, which 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, meaning general terms about things that somebody probably wants.

Danger signs include vagueness about which type of user is speaking, and generalization such as: usually, generally, often, normally, typically

Example

Users normally require early indication of intrusion into the system.

Do not use vague, undefined terms

Many words used informally to indicate system quality are too vague for use in requirements. Vague terms include, among others: 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-thinking terms include: 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