<?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>&lt;p>&#xD;
    Explanations and examples follow for each of the following common pitfalls to avoid in defining and writing&#xD;
    requirements (for more information, see &lt;a href=&quot;./../../../core.tech.common.base/guidances/supportingmaterials/references.tech_6CCF393.html&quot; guid=&quot;_9ToeIB83Edqsvps02rpOOg&quot;>[TEL06]&lt;/a>):&#xD;
&lt;/p>&#xD;
&lt;ul>&#xD;
    &lt;li>&#xD;
        Avoid ambiguity&#xD;
    &lt;/li>&#xD;
    &lt;li>&#xD;
        Don't make multiple requirements&#xD;
    &lt;/li>&#xD;
    &lt;li>&#xD;
        Never use let-out or escape words&#xD;
    &lt;/li>&#xD;
    &lt;li>&#xD;
        Don't ramble&#xD;
    &lt;/li>&#xD;
    &lt;li>&#xD;
        Resist designing the system&#xD;
    &lt;/li>&#xD;
    &lt;li>&#xD;
        Avoid mixing different kinds of requirements&#xD;
    &lt;/li>&#xD;
    &lt;li>&#xD;
        Do not speculate&#xD;
    &lt;/li>&#xD;
    &lt;li>&#xD;
        Do not use vague, undefined terms&#xD;
    &lt;/li>&#xD;
    &lt;li>&#xD;
        Do not express possibilities&#xD;
    &lt;/li>&#xD;
    &lt;li>&#xD;
        Avoid wishful thinking&#xD;
    &lt;/li>&#xD;
&lt;/ul>&#xD;
&lt;h4>&#xD;
    Avoid ambiguity&#xD;
&lt;/h4>&#xD;
&lt;p>&#xD;
    Avoidance of ambiguity is one of the subtlest and most difficult issues in writing requirements. Try to write as&#xD;
    clearly and explicitly as possible. Be specific. Remember, though, that if you carry this too far, the text becomes&#xD;
    dull and unreadable, which makes it difficult for other people to review. Although this guideline emphasizes&#xD;
    structured, written expression of requirements, informal text, diagrams, conversations, and phone calls are excellent&#xD;
    ways of removing ambiguity.&#xD;
&lt;/p>&#xD;
&lt;p>&#xD;
    Some constructions (such as the use of or and unless in requirements) allow different groups of readers to understand&#xD;
    different things from the same wording. Developers could use this technique deliberately, so as to postpone, until too&#xD;
    late, any possibility of the customer's asking for what was truly wanted. This is dangerous and could easily backfire.&#xD;
&lt;/p>&#xD;
&lt;p>&#xD;
    The only approach that works is for developers to make requirements as clear as possible, and for all stakeholders to&#xD;
    co-operate. In the long run, project success is in everybody's interest.&#xD;
&lt;/p>&#xD;
&lt;p>&#xD;
    Dangerous ambiguities can be caused by the word &lt;strong>or&lt;/strong> and also by many more-subtle errors.&#xD;
&lt;/p>&#xD;
&lt;h5>&#xD;
    Example&#xD;
&lt;/h5>&#xD;
&lt;p>&#xD;
    &lt;em>The same subsystem shall also be able to generate a visible or audible caution/warning signal for the attention of&#xD;
    the co-pilot or navigator.&lt;/em>&#xD;
&lt;/p>&#xD;
&lt;p>&#xD;
    Which subsystem? Is the signal to be visible, audible, or both? Is it both caution and warning, just caution, or just&#xD;
    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&#xD;
    what conditions?&#xD;
&lt;/p>&#xD;
&lt;h4>&#xD;
    Don't make multiple requirements&#xD;
&lt;/h4>&#xD;
&lt;p>&#xD;
    Requirements which contain conjunctions (words that join independent clauses together) are dangerous. Problems arise&#xD;
    when readers try to figure out which part applies, especially if the different clauses seem to conflict, or if the&#xD;
    individual parts apply separately. Multiple requirements also make verification more complex.&#xD;
&lt;/p>&#xD;
&lt;p>&#xD;
    Dangerous conjunctions include: and, or, but&#xD;
&lt;/p>&#xD;
&lt;h5>&#xD;
    Example&#xD;
&lt;/h5>&#xD;
&lt;p>&#xD;
    &lt;em>The battery low warning lamp shall light up when the voltage drops below 3.6 Volts, and the current workspace or&#xD;
    input data shall be saved.&lt;/em>&#xD;
&lt;/p>&#xD;
&lt;p>&#xD;
    Should the battery low warning lamp light up when the voltage drops and the workspace is saved? Should the battery low&#xD;
    warning lamp light up and the workspace be saved when the voltage drops?&#xD;
&lt;/p>&#xD;
&lt;h4>&#xD;
    Never use let-out or escape words&#xD;
&lt;/h4>&#xD;
&lt;p>&#xD;
    Requirements that include options or exceptions are dangerous. They seem to ask for something definite, but at the last&#xD;
    moment they back down and allow for other options. Problems arise when the requirements are to be tested, and someone&#xD;
    has to decide what (if anything) could prove the requirement was met.&#xD;
&lt;/p>&#xD;
&lt;p>&#xD;
    Dangerous words that imply exceptions include: if, when, but, except, unless, although.&#xD;
&lt;/p>&#xD;
&lt;h5>&#xD;
    Examples&#xD;
&lt;/h5>&#xD;
&lt;p>&#xD;
    &lt;em>The forward passenger doors shall open automatically when the aircraft has halted, except when the rear ramp is&#xD;
    deployed.&lt;/em>&#xD;
&lt;/p>&#xD;
&lt;p>&#xD;
    &lt;em>The fire alarm shall always be sounded when smoke is detected, unless the alarm is being tested or the engineer has&#xD;
    suppressed the alarm.&lt;/em>&#xD;
&lt;/p>&#xD;
&lt;p>&#xD;
    The latter sentence is a truly dangerous requirement!&#xD;
&lt;/p>&#xD;
&lt;h4>&#xD;
    Don't ramble&#xD;
&lt;/h4>&#xD;
&lt;p>&#xD;
    Long rambling sentences, especially when combined with arcane language, references to unreachable documents, and other&#xD;
    defects of writing, quickly lead to confusion and error.&#xD;
&lt;/p>&#xD;
&lt;h5>&#xD;
    Example&#xD;
&lt;/h5>&#xD;
&lt;p>&#xD;
    &lt;em>Provided that the designated input signals from the specified devices are received in the correct order where the&#xD;
    system is able to differentiate the designators, the output signal shall comply with the required framework of section&#xD;
    3.1.5 to indicate the desired input state.&lt;/em>&#xD;
&lt;/p>&#xD;
&lt;h4>&#xD;
    Resist designing the system&#xD;
&lt;/h4>&#xD;
&lt;p>&#xD;
    Requirements should specify the design envelope without unnecessary constraints on a specific design. If we supply too&#xD;
    much detail we start to design the system. Going too far is tempting for designers, especially when they come to their&#xD;
    favorite bits.&#xD;
&lt;/p>&#xD;
&lt;p>&#xD;
    Danger signs include names of components, materials, software objects/procedures, and database fields.&#xD;
&lt;/p>&#xD;
&lt;h5>&#xD;
    Example&#xD;
&lt;/h5>&#xD;
&lt;p>&#xD;
    &lt;em>The antenna shall be capable of receiving FM signals, using a copper core with nylon covering and a waterproof&#xD;
    hardened rubber shield.&lt;/em>&#xD;
&lt;/p>&#xD;
&lt;p>&#xD;
    Specifying design rather than actual need increases the cost of systems by placing needless constraints on development&#xD;
    and manufacture. Often knowing why is much better than knowing what.&#xD;
&lt;/p>&#xD;
&lt;h4>&#xD;
    Avoid mixing different kinds of requirements&#xD;
&lt;/h4>&#xD;
&lt;p>&#xD;
    The user requirements form a complete model of what users want. They need to be organized coherently to show gaps and&#xD;
    overlaps. The same applies to system requirements, which form a complete functional model of the proposed system. A&#xD;
    quick road to confusion is to mix up requirements for users, systems, and how the system should be designed, tested, or&#xD;
    installed.&#xD;
&lt;/p>&#xD;
&lt;p>&#xD;
    Danger signs are any references to system, design, testing, or installation.&#xD;
&lt;/p>&#xD;
&lt;h5>&#xD;
    Example&#xD;
&lt;/h5>&#xD;
&lt;p>&#xD;
    &lt;em>The user shall be able to view the currently selected channel number which shall be displayed in 14pt Swiss type on&#xD;
    an LCD panel tested to Federal Regulation Standard 567-89 and mounted with shockproof rubber washers.&lt;/em>&#xD;
&lt;/p>&#xD;
&lt;h4>&#xD;
    Do not speculate&#xD;
&lt;/h4>&#xD;
&lt;p>&#xD;
    Requirements are part of a contract between customer and developer. There is no room for wish lists, meaning general&#xD;
    terms about things that somebody probably wants.&#xD;
&lt;/p>&#xD;
&lt;p>&#xD;
    Danger signs include vagueness about which type of user is speaking, and generalization such as: usually, generally,&#xD;
    often, normally, typically&#xD;
&lt;/p>&#xD;
&lt;h5>&#xD;
    Example&#xD;
&lt;/h5>&#xD;
&lt;p>&#xD;
    &lt;em>Users normally require early indication of intrusion into the system.&lt;/em>&#xD;
&lt;/p>&#xD;
&lt;h4>&#xD;
    Do not use vague, undefined terms&#xD;
&lt;/h4>&#xD;
&lt;p>&#xD;
    Many words used informally to indicate system quality are too vague for use in requirements. Vague terms include, among&#xD;
    others: user-friendly, versatile, flexible, approximately, as possible&#xD;
&lt;/p>&#xD;
&lt;p>&#xD;
    Requirements using these terms are unverifiable because there is no definite test to show whether the system has the&#xD;
    indicated property.&#xD;
&lt;/p>&#xD;
&lt;h5>&#xD;
    Examples&#xD;
&lt;/h5>&#xD;
&lt;p>&#xD;
    &lt;em>The print dialog shall be versatile and user-friendly.&lt;/em>&#xD;
&lt;/p>&#xD;
&lt;p>&#xD;
    &lt;em>The OK status indicator lamp shall be illuminated as soon as possible after the system self-check is&#xD;
    completed.&lt;/em>&#xD;
&lt;/p>&#xD;
&lt;h4>&#xD;
    Do not express possibilities&#xD;
&lt;/h4>&#xD;
&lt;p>&#xD;
    Suggestions that are not explicitly stated as requirements are invariably ignored by developers.&#xD;
&lt;/p>&#xD;
&lt;p>&#xD;
    &quot;Possible options&quot; are indicated with terms such as: may, might, should, ought, could, perhaps, probably&#xD;
&lt;/p>&#xD;
&lt;h5>&#xD;
    Example&#xD;
&lt;/h5>&#xD;
&lt;p>&#xD;
    &lt;em>The reception subsystem probably ought to be powerful enough to receive a signal inside a steel-framed&#xD;
    building.&lt;/em>&#xD;
&lt;/p>&#xD;
&lt;h4>&#xD;
    Avoid wishful thinking&#xD;
&lt;/h4>&#xD;
&lt;p>&#xD;
    Engineering is a real-world activity. No system or component is perfect. Wishful thinking means asking for the&#xD;
    impossible.&#xD;
&lt;/p>&#xD;
&lt;p>&#xD;
    Wishful-thinking terms include: reliable, safe, handle all unexpected failures, please all users, run on all platforms,&#xD;
    never fail, upgradeable to all future situations&#xD;
&lt;/p>&#xD;
&lt;h5>&#xD;
    Examples&#xD;
&lt;/h5>&#xD;
&lt;p>&#xD;
    &lt;em>The gearbox shall be 100% safe in normal operation.&lt;/em>&#xD;
&lt;/p>&#xD;
&lt;p>&#xD;
    &lt;em>The network shall handle all unexpected errors without crashing.&lt;/em>&#xD;
&lt;/p></mainDescription>
</org.eclipse.epf.uma:ContentDescription>