Guideline: Writing Good Requirements
This guideline describes ways of writing good requirements.
Relationships
Main Description

To write a good requirement, you must write it as a complete sentence, with a subject and a predicate. The subject 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.

Thus, you can analyze a requirement from a grammatical point of view. For example:

The order entry clerk shall be able to complete 10 customer orders in less than two hours.

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).

In stakeholder requirements, use of the verb form "shall be able to" makes it clear that the requirement specifies something that the stakeholder must be able to do, but is not (necessarily) forced to do. In system requirements, the verb form "shall <action>" makes it clear that the system must perform this action under the specified conditions.

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.

Words such as all, every, and some can lead to ambiguity. Can you be certain that you have taken into account all cases?  What proportion of the whole does some represent?

The following simple guidelines will help you write better requirements. For consistency, these examples are all in the context of an aircraft. [TEL06]

  • Define one requirement at a time. For example,

The pilot shall be able to control the aircraft's angle of climb with one hand.

The pilot shall be able to feel the angle of climb from the climb control.

  • Avoid conjunctions (and, or) that make multiple requirements. For example, use:

The navigator shall be able to view the aircraft's position relative to the route's radio beacons.

The navigator shall be able to view the aircraft's position as estimated by inertial guidance.

instead of:

The navigator shall be able to view the aircrafts position relative to the route's radio beacons or as estimated by the inertial guidance.

The latter form is potentially dangerous because it is not clear whether the "or" indicates that the navigator can chose which method to use for navigation or that the developers can decide which to implement.

  • Avoid let-out clauses or words that imply options or exceptions (unless, except, if necessary, but). 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:

The system shall provide 100% of rating in normal conditions.

The system shall be capable of providing up to 125% of rating for the first 15 minutes in an emergency condition.

The system shall provide a minimum of 90% of rating for not less than 15 minutes following first 15 minutes in an emergency condition.

The system shall activate a reduced rating exception if a minimum of 95% of rating is not maintained in an emergency condition.

instead of:

The system shall perform at the maximum rating at all times except that in emergencies it shall be capable of providing up to 125% of rating unless the emergency condition continues for more than 15 minutes in which case the rating shall be reduced to 105% but 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.

  • Use simple, direct sentences.

The pilot shall be able to see the airspeed indicator.

  • Use simple, ordinary words as much as possible, especially if your audience is international, which makes accurate translation a concern.

The airline shall be able to convert the aircraft from business to holiday charter use in less than 12 hours.

Note: There is no need to use words such as reconfigured.

  • Identify the type of user who needs each requirement.

The navigator shall be able to...

  • Focus on stating what result you will provide for that type of user.

...view storm clouds by radar...

  • Define verifiable criteria

...at least 100 miles ahead.

  • Use To Be Confirmed (TBC) to flag a requirement is likely to change or is not yet definite. This helps identify outstanding work. For example:

The aircraft shall be able to land safely on airstrips with a minimum length of 1000 meters (TBC).

  • Use To Be Determined (TBD) where it is known that a specific requirement will be needed, but the details are not yet know (known-unknowns). This also helps identify outstanding work. For example,

The aircraft shall be able to land safely on airstrips with a minimum length of TBD meters.