<?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.6/uma.ecore" xmlns:epf="http://www.eclipse.org/epf" epf:version="1.5.1" xmi:id="-Q72-dNdHnZ93aRXAB_d34A" name="requirement_pitfalls_1,_1AOsMO0JEdqHTdbLTmC5IQ" guid="-Q72-dNdHnZ93aRXAB_d34A" authors="Chris Sibbald" changeDate="2007-07-18T22:54:11.979+0330" version="0.2">
  <mainDescription>&lt;p>&#xD;
    Research and experience shows that requirements errors are very common, accounting for as much as 56% of all errors&#xD;
    made during development &lt;a class=&quot;elementLinkWithUserText&quot;&#xD;
    href=&quot;./../../../openup/guidances/supportingmaterials/references.html#TAV84&quot;&#xD;
    guid=&quot;_9ToeIB83Edqsvps02rpOOg&quot;>[TAV84]&lt;/a>.&amp;nbsp; Compounding this problem is the fact that the cost of correcting&#xD;
    requirements errors increases exponentially throughout the software development lifecycle &lt;a&#xD;
    class=&quot;elementLinkWithUserText&quot; href=&quot;./../../../openup/guidances/supportingmaterials/references.html#BOE88&quot;&#xD;
    guid=&quot;_9ToeIB83Edqsvps02rpOOg&quot;>[BOE88]&lt;/a>.&#xD;
&lt;/p>&#xD;
&lt;p>&#xD;
    Frederick Brooks summarized this situation nicely:&#xD;
&lt;/p>&#xD;
&lt;blockquote>&#xD;
    The hardest single part of building a software system is deciding what to build. No other part of the conceptual work&#xD;
    is as difficult as establishing the detailed technical requirements…. No other part of the work so cripples the&#xD;
    resulting system if done wrong. No other part is as difficult to rectify later.&lt;a class=&quot;elementLinkWithUserText&quot;&#xD;
    href=&quot;./../../../openup/guidances/supportingmaterials/references.html#BRO87&quot; guid=&quot;_9ToeIB83Edqsvps02rpOOg&quot;>[BRO87]&lt;/a>&#xD;
&lt;/blockquote>&#xD;
&lt;p>&#xD;
    Therefore, it is critical that you detect requirements errors as early as possible, before they propagate to design,&#xD;
    implementation, and test artifacts.&#xD;
&lt;/p>&#xD;
&lt;h1>&#xD;
    What to avoid when writing requirements&#xD;
&lt;/h1>&#xD;
&lt;p>&#xD;
    Although there is sure way to eliminate requirements errors in general, there are common pitfalls in writing&#xD;
    requirements that are relatively easy to avoid &lt;a&#xD;
    href=&quot;./../../../openup/guidances/supportingmaterials/references.html#TEL06&quot;&#xD;
    guid=&quot;_9ToeIB83Edqsvps02rpOOg&quot;>[TEL06]&lt;/a>.&#xD;
&lt;/p>&#xD;
&lt;h2>&#xD;
    Ambiguity&#xD;
&lt;/h2>&#xD;
&lt;p>&#xD;
    Avoiding ambiguity is one of the most difficult mandates in writing requirements. Try to write as clearly and&#xD;
    explicitly as possible. Be specific. If you must use vague or ambiguous terms, make sure that you define them in the&#xD;
    glossary.&#xD;
&lt;/p>&#xD;
&lt;p>&#xD;
    Have several colleagues and stakeholders review your requirements to ensure a consistent, common understanding.&#xD;
    Although there is no definitive test for ambiguity, other than consensus, some dangerous ambiguities can be caused by&#xD;
    the use of the words &lt;b>for, or&lt;/b>, and &lt;strong>unless&lt;/strong>.&amp;nbsp;&#xD;
&lt;/p>&#xD;
&lt;blockquote dir=&quot;ltr&quot; style=&quot;MARGIN-RIGHT: 0px&quot;>&#xD;
    &lt;b>Example&lt;/b> &#xD;
    &lt;p>&#xD;
        &quot;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.&quot;&#xD;
    &lt;/p>&#xD;
    &lt;p>&#xD;
        Which subsystem? Is the signal to be visible, audible, or both? Is this both a caution and a warning, just a&#xD;
        caution, or just a warning? Is it for both the co-pilot and the navigator or just one of them? If just one of them,&#xD;
        which one and under what conditions?&#xD;
    &lt;/p>&#xD;
&lt;/blockquote>&#xD;
&lt;h2>&#xD;
    Multiple requirements&#xD;
&lt;/h2>&#xD;
&lt;p>&#xD;
    Requirements that 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: &lt;b>and, or, but&lt;/b>.&#xD;
&lt;/p>&#xD;
&lt;blockquote dir=&quot;ltr&quot; style=&quot;MARGIN-RIGHT: 0px&quot;>&#xD;
    &lt;b>Example&lt;/b> &#xD;
    &lt;p>&#xD;
        &quot;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.&quot;&#xD;
    &lt;/p>&#xD;
    &lt;p>&#xD;
        Should the battery low-warning lamp light up when the voltage drops and when the workspace is saved? Should the&#xD;
        battery low warning lamp light up and the workspace be saved when the voltage drops?&#xD;
    &lt;/p>&#xD;
&lt;/blockquote>&#xD;
&lt;h2>&#xD;
    Let-out or escape&amp;nbsp;clauses&#xD;
&lt;/h2>&#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 other options. Problems arise when the requirements are to be tested, and someone has&#xD;
    to decide what (if anything) could prove that the requirement was met.&#xD;
&lt;/p>&#xD;
&lt;p>&#xD;
    Dangerous words that imply exceptions include: &lt;b>if, when, but, except, unless, although&lt;/b>.&#xD;
&lt;/p>&#xD;
&lt;blockquote dir=&quot;ltr&quot; style=&quot;MARGIN-RIGHT: 0px&quot;>&#xD;
    &lt;b>Examples&lt;/b> &#xD;
    &lt;p>&#xD;
        &quot;The forward passenger doors shall open automatically when the aircraft has halted, except when the rear ramp is&#xD;
        deployed.&quot;&#xD;
    &lt;/p>&#xD;
    &lt;p>&#xD;
        &quot;The fire alarm shall always be sounded when smoke is detected, unless the alarm is being tested or the engineer&#xD;
        has suppressed the alarm.&quot;&#xD;
    &lt;/p>&#xD;
    &lt;p>&#xD;
        The latter sentence is a truly dangerous requirement!&#xD;
    &lt;/p>&#xD;
&lt;/blockquote>&#xD;
&lt;h2>&#xD;
    Rambling&#xD;
&lt;/h2>&#xD;
&lt;p>&#xD;
    Long, rambling sentences, especially when combined with arcane language or references to unreachable documents, quickly&#xD;
    lead to confusion and error.&#xD;
&lt;/p>&#xD;
&lt;blockquote dir=&quot;ltr&quot; style=&quot;MARGIN-RIGHT: 0px&quot;>&#xD;
    &lt;b>Example&lt;/b> &#xD;
    &lt;p>&#xD;
        &quot;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&#xD;
        section 3.1.5 to indicate the desired input state.&quot;&#xD;
    &lt;/p>&#xD;
&lt;/blockquote>&#xD;
&lt;h2>&#xD;
    Premature design&#xD;
&lt;/h2>&#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 &lt;b>names of components, materials, software objects&lt;/b> or &lt;b>procedures&lt;/b>, and &lt;b>database&#xD;
    fields&lt;/b>.&#xD;
&lt;/p>&#xD;
&lt;blockquote dir=&quot;ltr&quot; style=&quot;MARGIN-RIGHT: 0px&quot;>&#xD;
    &lt;b>Example&lt;/b> &#xD;
    &lt;p>&#xD;
        &quot;The antenna shall be capable of receiving FM signals, using a copper core with nylon covering and a waterproof&#xD;
        hardened rubber shield.&quot;&#xD;
    &lt;/p>&#xD;
    &lt;p>&#xD;
        Specifying design rather than actual need increases the cost of systems by placing needless constraints on&#xD;
        development and manufacture. Often, knowing &lt;i>why&lt;/i> is much better than knowing &lt;i>what&lt;/i>.&#xD;
    &lt;/p>&#xD;
&lt;/blockquote>&#xD;
&lt;h2>&#xD;
    Mixing different kinds of requirements&#xD;
&lt;/h2>&#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 &lt;b>system, design, testing&lt;/b>, or &lt;b>installation&lt;/b>.&#xD;
&lt;/p>&#xD;
&lt;blockquote dir=&quot;ltr&quot; style=&quot;MARGIN-RIGHT: 0px&quot;>&#xD;
    &lt;b>Example&lt;/b> &#xD;
    &lt;p>&#xD;
        &quot;The user shall be able to view the currently selected channel number which shall be displayed in 14pt Swiss type&#xD;
        on an LCD panel tested to Federal Regulation Standard 567-89 and mounted with shockproof rubber washers.&quot;&#xD;
    &lt;/p>&#xD;
&lt;/blockquote>&#xD;
&lt;h2>&#xD;
    Speculation&#xD;
&lt;/h2>&#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 &lt;b>which type of user is speaking&lt;/b> and generalizations, such as &lt;b>usually,&#xD;
    generally, often, normally, typically&lt;/b>.&#xD;
&lt;/p>&#xD;
&lt;blockquote dir=&quot;ltr&quot; style=&quot;MARGIN-RIGHT: 0px&quot;>&#xD;
    &lt;b>Example&lt;/b> &#xD;
    &lt;p>&#xD;
        &quot;Users normally require early indication of intrusion into the system.&quot;&#xD;
    &lt;/p>&#xD;
&lt;/blockquote>&#xD;
&lt;h2>&#xD;
    Vague, undefined terms&#xD;
&lt;/h2>&#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: &lt;b>user-friendly, versatile, flexible, approximately, as possible&lt;/b>.&#xD;
&lt;/p>&#xD;
&lt;p>&#xD;
    Requirements using these terms are unverifiable, because there is no definitive test to show whether the system has the&#xD;
    indicated property.&#xD;
&lt;/p>&#xD;
&lt;blockquote dir=&quot;ltr&quot; style=&quot;MARGIN-RIGHT: 0px&quot;>&#xD;
    &lt;b>Examples&lt;/b> &#xD;
    &lt;p>&#xD;
        &quot;The print dialog shall be versatile and user-friendly.&quot;&#xD;
    &lt;/p>&#xD;
    &lt;p>&#xD;
        &quot;The OK status indicator lamp shall be illuminated as soon as possible after the system self-check is completed.&quot;&#xD;
    &lt;/p>&#xD;
&lt;/blockquote>&#xD;
&lt;h2>&#xD;
    Expressing mere possibilities&#xD;
&lt;/h2>&#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 &lt;b>may, might, should, ought, could, perhaps, probably&lt;/b>.&#xD;
&lt;/p>&#xD;
&lt;blockquote dir=&quot;ltr&quot; style=&quot;MARGIN-RIGHT: 0px&quot;>&#xD;
    &lt;b>Example&lt;/b> &#xD;
    &lt;p>&#xD;
        &quot;The reception subsystem probably ought to be powerful enough to receive a signal inside a steel-framed building.&quot;&#xD;
    &lt;/p>&#xD;
&lt;/blockquote>&#xD;
&lt;h2>&#xD;
    Wishful thinking&#xD;
&lt;/h2>&#xD;
&lt;p>&#xD;
    Wishful thinking means asking for the impossible. Engineering is a real-world activity, and no system or component is&#xD;
    perfect.&#xD;
&lt;/p>&#xD;
&lt;p>&#xD;
    Wishful-thinking terms include &lt;b>reliable, safe, handle all unexpected failures, please all users, run on all&#xD;
    platforms, never fail, upgradeable to all future situations&lt;/b>.&#xD;
&lt;/p>&#xD;
&lt;blockquote dir=&quot;ltr&quot; style=&quot;MARGIN-RIGHT: 0px&quot;>&#xD;
    &lt;b>Examples&lt;/b> &#xD;
    &lt;p>&#xD;
        &quot;The gearbox shall be 100% safe in normal operation.&quot;&#xD;
    &lt;/p>&#xD;
    &lt;p>&#xD;
        &quot;The network shall handle all unexpected errors without crashing.&quot;&#xD;
    &lt;/p>&#xD;
&lt;/blockquote></mainDescription>
</org.eclipse.epf.uma:ContentDescription>
