| <?xml version="1.0" encoding="UTF-8"?> |
| <org.eclipse.epf.uma:ContentDescription xmi:version="2.0" |
| xmlns:xmi="http://www.omg.org/XMI" xmlns:org.eclipse.epf.uma="http://www.eclipse.org/epf/uma/1.0.5/uma.ecore" |
| xmlns:rmc="http://www.ibm.com/rmc" rmc:version="7.5.0" xmlns:epf="http://www.eclipse.org/epf" |
| epf:version="1.5.0" xmi:id="-Q72-dNdHnZ93aRXAB_d34A" |
| name="requirement_pitfalls_1,_1AOsMO0JEdqHTdbLTmC5IQ" guid="-Q72-dNdHnZ93aRXAB_d34A" |
| authors="Chris Sibbald" changeDate="2006-09-27T10:14:43.000-0700" version="0.2"> |
| <mainDescription><p>
 |
| Explanations and examples follow for each of the following common pitfalls to avoid in defining and writing
 |
| requirements (for more information, see <a href="./../../../core.tech.common.base/guidances/supportingmaterials/references.tech_6CCF393.html" guid="_9ToeIB83Edqsvps02rpOOg">[TEL06]</a>):
 |
| </p>
 |
| <ul>
 |
| <li>
 |
| Avoid ambiguity
 |
| </li>
 |
| <li>
 |
| Don't make multiple requirements
 |
| </li>
 |
| <li>
 |
| Never use let-out or escape words
 |
| </li>
 |
| <li>
 |
| Don't ramble
 |
| </li>
 |
| <li>
 |
| Resist designing the system
 |
| </li>
 |
| <li>
 |
| Avoid mixing different kinds of requirements
 |
| </li>
 |
| <li>
 |
| Do not speculate
 |
| </li>
 |
| <li>
 |
| Do not use vague, undefined terms
 |
| </li>
 |
| <li>
 |
| Do not express possibilities
 |
| </li>
 |
| <li>
 |
| Avoid wishful thinking
 |
| </li>
 |
| </ul>
 |
| <h4>
 |
| Avoid ambiguity
 |
| </h4>
 |
| <p>
 |
| 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.
 |
| </p>
 |
| <p>
 |
| 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.
 |
| </p>
 |
| <p>
 |
| 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.
 |
| </p>
 |
| <p>
 |
| Dangerous ambiguities can be caused by the word <strong>or</strong> and also by many more-subtle errors.
 |
| </p>
 |
| <h5>
 |
| Example
 |
| </h5>
 |
| <p>
 |
| <em>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.</em>
 |
| </p>
 |
| <p>
 |
| 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?
 |
| </p>
 |
| <h4>
 |
| Don't make multiple requirements
 |
| </h4>
 |
| <p>
 |
| 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.
 |
| </p>
 |
| <p>
 |
| Dangerous conjunctions include: and, or, but
 |
| </p>
 |
| <h5>
 |
| Example
 |
| </h5>
 |
| <p>
 |
| <em>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.</em>
 |
| </p>
 |
| <p>
 |
| 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?
 |
| </p>
 |
| <h4>
 |
| Never use let-out or escape words
 |
| </h4>
 |
| <p>
 |
| 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.
 |
| </p>
 |
| <p>
 |
| Dangerous words that imply exceptions include: if, when, but, except, unless, although.
 |
| </p>
 |
| <h5>
 |
| Examples
 |
| </h5>
 |
| <p>
 |
| <em>The forward passenger doors shall open automatically when the aircraft has halted, except when the rear ramp is
 |
| deployed.</em>
 |
| </p>
 |
| <p>
 |
| <em>The fire alarm shall always be sounded when smoke is detected, unless the alarm is being tested or the engineer has
 |
| suppressed the alarm.</em>
 |
| </p>
 |
| <p>
 |
| The latter sentence is a truly dangerous requirement!
 |
| </p>
 |
| <h4>
 |
| Don't ramble
 |
| </h4>
 |
| <p>
 |
| Long rambling sentences, especially when combined with arcane language, references to unreachable documents, and other
 |
| defects of writing, quickly lead to confusion and error.
 |
| </p>
 |
| <h5>
 |
| Example
 |
| </h5>
 |
| <p>
 |
| <em>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.</em>
 |
| </p>
 |
| <h4>
 |
| Resist designing the system
 |
| </h4>
 |
| <p>
 |
| 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.
 |
| </p>
 |
| <p>
 |
| Danger signs include names of components, materials, software objects/procedures, and database fields.
 |
| </p>
 |
| <h5>
 |
| Example
 |
| </h5>
 |
| <p>
 |
| <em>The antenna shall be capable of receiving FM signals, using a copper core with nylon covering and a waterproof
 |
| hardened rubber shield.</em>
 |
| </p>
 |
| <p>
 |
| 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.
 |
| </p>
 |
| <h4>
 |
| Avoid mixing different kinds of requirements
 |
| </h4>
 |
| <p>
 |
| 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.
 |
| </p>
 |
| <p>
 |
| Danger signs are any references to system, design, testing, or installation.
 |
| </p>
 |
| <h5>
 |
| Example
 |
| </h5>
 |
| <p>
 |
| <em>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.</em>
 |
| </p>
 |
| <h4>
 |
| Do not speculate
 |
| </h4>
 |
| <p>
 |
| 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.
 |
| </p>
 |
| <p>
 |
| Danger signs include vagueness about which type of user is speaking, and generalization such as: usually, generally,
 |
| often, normally, typically
 |
| </p>
 |
| <h5>
 |
| Example
 |
| </h5>
 |
| <p>
 |
| <em>Users normally require early indication of intrusion into the system.</em>
 |
| </p>
 |
| <h4>
 |
| Do not use vague, undefined terms
 |
| </h4>
 |
| <p>
 |
| 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
 |
| </p>
 |
| <p>
 |
| Requirements using these terms are unverifiable because there is no definite test to show whether the system has the
 |
| indicated property.
 |
| </p>
 |
| <h5>
 |
| Examples
 |
| </h5>
 |
| <p>
 |
| <em>The print dialog shall be versatile and user-friendly.</em>
 |
| </p>
 |
| <p>
 |
| <em>The OK status indicator lamp shall be illuminated as soon as possible after the system self-check is
 |
| completed.</em>
 |
| </p>
 |
| <h4>
 |
| Do not express possibilities
 |
| </h4>
 |
| <p>
 |
| Suggestions that are not explicitly stated as requirements are invariably ignored by developers.
 |
| </p>
 |
| <p>
 |
| "Possible options" are indicated with terms such as: may, might, should, ought, could, perhaps, probably
 |
| </p>
 |
| <h5>
 |
| Example
 |
| </h5>
 |
| <p>
 |
| <em>The reception subsystem probably ought to be powerful enough to receive a signal inside a steel-framed
 |
| building.</em>
 |
| </p>
 |
| <h4>
 |
| Avoid wishful thinking
 |
| </h4>
 |
| <p>
 |
| Engineering is a real-world activity. No system or component is perfect. Wishful thinking means asking for the
 |
| impossible.
 |
| </p>
 |
| <p>
 |
| Wishful-thinking terms include: reliable, safe, handle all unexpected failures, please all users, run on all platforms,
 |
| never fail, upgradeable to all future situations
 |
| </p>
 |
| <h5>
 |
| Examples
 |
| </h5>
 |
| <p>
 |
| <em>The gearbox shall be 100% safe in normal operation.</em>
 |
| </p>
 |
| <p>
 |
| <em>The network shall handle all unexpected errors without crashing.</em>
 |
| </p></mainDescription> |
| </org.eclipse.epf.uma:ContentDescription> |
