| <?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:epf="http://www.eclipse.org/epf" epf:version="1.5.0" xmi:id="-AJQLv2ldVv5KN9eUbdQe_g" |
| name="new_guideline,_6jXzYNcKEdqz_d2XWoVt6Q" guid="-AJQLv2ldVv5KN9eUbdQe_g" changeDate="2007-07-23T12:28:34.641-0700" |
| version="1.0.0"> |
| <mainDescription><p>
 |
| To write a good requirement, you must write it as a complete sentence, with a subject and a predicate. The
 |
| subject&nbsp;is an Actor, a stakeholder, the system under development, or a design entity that is related to the
 |
| requirement. The predicate specifies an action or intended result that is done for, by, with, or to the subject, often
 |
| including conditions and performance criteria.
 |
| </p>
 |
| <p>
 |
| Thus, you can analyze a requirement from a grammatical point of view. For example:
 |
| </p>
 |
| <blockquote>
 |
| <p>
 |
| <em>The order entry clerk&nbsp;shall be able to complete 10 customer orders in less than two hours.</em>
 |
| </p>
 |
| </blockquote>
 |
| <p>
 |
| This requirement has a subject (the order entry clerk, who is an Actor), a specific and measurable end state (10
 |
| customer orders completed), and a performance criterion (in less than two hours).
 |
| </p>
 |
| <p>
 |
| In stakeholder requirements, use of the verb form "shall be able to" makes it clear that the requirement&nbsp;specifies
 |
| something that the stakeholder must be <strong>able</strong> to do, but is not (necessarily) forced to do. In system
 |
| requirements, the verb form "shall &lt;action&gt;" makes it clear that the system must perform this action under the
 |
| specified conditions.
 |
| </p>
 |
| <p>
 |
| Numbered and bulleted lists may make writing clearer in some cases, but each list item must be a complete requirement
 |
| in itself to maximize the benefit of any traceability information.
 |
| </p>
 |
| <p>
 |
| Words such as <strong>all</strong>, <strong>every,</strong> and <strong>some</strong> can lead to ambiguity. Can you be
 |
| certain that you have taken into account <strong>all</strong> cases?&nbsp; What proportion of the whole&nbsp;does
 |
| <strong>some</strong> represent?
 |
| </p>
 |
| <p>
 |
| The following simple guidelines will help you&nbsp;write better requirements. For consistency, these examples are all
 |
| in the context of an aircraft. <a class="elementlinkwithusertext"
 |
| href="./../../../openup/guidances/supportingmaterials/references.html#TEL06" guid="_9ToeIB83Edqsvps02rpOOg">[TEL06]</a>
 |
| </p>
 |
| <ul>
 |
| <li>
 |
| Define one requirement at a time. For example,
 |
| </li>
 |
| </ul>
 |
| <blockquote dir="ltr" style="MARGIN-RIGHT: 0px">
 |
| <blockquote dir="ltr" style="MARGIN-RIGHT: 0px">
 |
| <p>
 |
| <em>The pilot shall be able to control the aircraft's angle of climb with one hand.</em>
 |
| </p>
 |
| <p>
 |
| <em>The pilot shall be able to feel the angle of climb from the climb control.</em>
 |
| </p>
 |
| </blockquote>
 |
| </blockquote>
 |
| <ul>
 |
| <li>
 |
| Avoid conjunctions (<b>and</b>, <b>or</b>) that make multiple requirements. For example, use:
 |
| </li>
 |
| </ul>
 |
| <blockquote>
 |
| <blockquote dir="ltr" style="MARGIN-RIGHT: 0px">
 |
| <p>
 |
| <em>The navigator shall be able to view the aircraft's position relative to the route's radio beacons.</em>
 |
| </p>
 |
| <p>
 |
| <em>The navigator shall be able to view the aircraft's position as estimated by inertial guidance.</em>
 |
| </p>
 |
| </blockquote>
 |
| <p>
 |
| instead of:
 |
| </p>
 |
| <blockquote dir="ltr" style="MARGIN-RIGHT: 0px">
 |
| <p>
 |
| <em>The navigator shall be able to view the aircrafts position relative to the route's radio beacons or as
 |
| estimated by the inertial guidance.</em>
 |
| </p>
 |
| </blockquote>
 |
| <p>
 |
| The latter form&nbsp;is potentially dangerous because it is not clear whether the "or"&nbsp;indicates that the
 |
| navigator can chose which method to use for navigation or that the developers can decide which to implement.
 |
| </p>
 |
| </blockquote>
 |
| <ul>
 |
| <li>
 |
| Avoid let-out clauses or words that imply options or exceptions (<b>unless, except, if necessary, but</b>). These
 |
| are dangerous since it is difficult to determine when the requirement applies. It is better to write separate
 |
| requirements addressing each specific condition, or state of the system. For example, use:
 |
| </li>
 |
| </ul>
 |
| <blockquote dir="ltr" style="MARGIN-RIGHT: 0px">
 |
| <blockquote dir="ltr" style="MARGIN-RIGHT: 0px">
 |
| <p>
 |
| <em>The system shall provide 100% of rating in normal conditions.</em>
 |
| </p>
 |
| <p>
 |
| <em>The system shall be capable of providing&nbsp;up to&nbsp;125% of rating&nbsp;for the first 15 minutes in
 |
| an&nbsp;emergency condition.</em>
 |
| </p>
 |
| <p>
 |
| <em>The system shall provide a minimum of 90% of rating for not less than 15 minutes following first 15 minutes
 |
| in an emergency condition.</em>
 |
| </p>
 |
| <p>
 |
| <em>The system shall activate a reduced rating exception if a minimum of 95% of rating&nbsp;is
 |
| not&nbsp;maintained in an emergency condition.</em>
 |
| </p>
 |
| </blockquote>
 |
| <p>
 |
| instead of:
 |
| </p>
 |
| <blockquote dir="ltr" style="MARGIN-RIGHT: 0px">
 |
| <p>
 |
| <em>The system shall perform at the maximum rating at all times <strong>except</strong> that in emergencies it
 |
| shall be capable of providing up to 125% of rating <strong>unless</strong> the emergency condition continues
 |
| for more than 15 minutes in which case the rating shall be reduced to 105% <strong>but</strong> in the event
 |
| that only 95% can be achieved then the system shall activate a reduced rating exception and shall maintain the
 |
| rating within 10% of the stated values for a minimum of 30 minutes.</em>
 |
| </p>
 |
| </blockquote>
 |
| </blockquote>
 |
| <ul>
 |
| <li>
 |
| Use simple, direct sentences.
 |
| </li>
 |
| </ul>
 |
| <blockquote dir="ltr" style="MARGIN-RIGHT: 0px">
 |
| <blockquote dir="ltr" style="MARGIN-RIGHT: 0px">
 |
| <p>
 |
| <em>The pilot shall be able to see the airspeed indicator.</em>
 |
| </p>
 |
| </blockquote>
 |
| </blockquote>
 |
| <ul>
 |
| <li>
 |
| Use simple, ordinary words as much as possible, especially if your audience is international, which makes accurate
 |
| translation a concern.
 |
| </li>
 |
| </ul>
 |
| <blockquote dir="ltr" style="MARGIN-RIGHT: 0px">
 |
| <blockquote dir="ltr" style="MARGIN-RIGHT: 0px">
 |
| <p>
 |
| <em>The airline shall be able to convert the aircraft from business to holiday charter use in less than 12
 |
| hours.</em>
 |
| </p>
 |
| <p>
 |
| <strong>Note:</strong> There is no need to use words such as <strong>reconfigured.</strong>
 |
| </p>
 |
| </blockquote>
 |
| </blockquote>
 |
| <ul>
 |
| <li>
 |
| Identify the type of user who needs each requirement.
 |
| </li>
 |
| </ul>
 |
| <blockquote dir="ltr" style="MARGIN-RIGHT: 0px">
 |
| <blockquote dir="ltr" style="MARGIN-RIGHT: 0px">
 |
| <p>
 |
| <em>The navigator shall be able to...</em>
 |
| </p>
 |
| </blockquote>
 |
| </blockquote>
 |
| <ul>
 |
| <li>
 |
| Focus on stating what result you will provide for that type of user.
 |
| </li>
 |
| </ul>
 |
| <blockquote dir="ltr" style="MARGIN-RIGHT: 0px">
 |
| <blockquote dir="ltr" style="MARGIN-RIGHT: 0px">
 |
| <p>
 |
| <em>...view storm clouds by radar...</em>
 |
| </p>
 |
| </blockquote>
 |
| </blockquote>
 |
| <ul>
 |
| <li>
 |
| Define verifiable criteria
 |
| </li>
 |
| </ul>
 |
| <blockquote dir="ltr" style="MARGIN-RIGHT: 0px">
 |
| <blockquote>
 |
| <p>
 |
| <em>...at least 100 miles ahead.</em>
 |
| </p>
 |
| </blockquote>
 |
| </blockquote>
 |
| <ul dir="ltr">
 |
| <li>
 |
| <div>
 |
| Use <strong>To Be Confirmed</strong> (TBC) to flag a requirement is likely to change or is not yet definite.
 |
| This helps identify&nbsp;outstanding work.&nbsp;For example:
 |
| </div>
 |
| </li>
 |
| </ul>
 |
| <blockquote dir="ltr" style="MARGIN-RIGHT: 0px">
 |
| <blockquote dir="ltr" style="MARGIN-RIGHT: 0px">
 |
| <p dir="ltr">
 |
| <em>The aircraft shall be able to land safely on airstrips with a minimum length of 1000 meters (TBC).</em>
 |
| </p>
 |
| </blockquote>
 |
| </blockquote>
 |
| <ul dir="ltr">
 |
| <li>
 |
| <div>
 |
| Use <strong>To Be Determined</strong> (TBD) where it is known that a specific&nbsp;requirement will be needed,
 |
| but the details are not yet know (known-unknowns). This also helps identify outstanding work. For example,
 |
| </div>
 |
| </li>
 |
| </ul>
 |
| <blockquote dir="ltr" style="MARGIN-RIGHT: 0px">
 |
| <blockquote dir="ltr" style="MARGIN-RIGHT: 0px">
 |
| <p dir="ltr">
 |
| <em>The aircraft shall be able to land safely on airstrips with a minimum length of TBD meters.</em>
 |
| </p>
 |
| </blockquote>
 |
| </blockquote></mainDescription> |
| </org.eclipse.epf.uma:ContentDescription> |
