Guidelines for Writing Requirement Statements

There is no formulaic way to write excellent requirements; the best teacher is experience. The problems you have encountered in the past will teach you much. Excellent requirements documents follow effective technical-writing style guidelines and employ user terminology rather than computer jargon. Keep the following suggestions in mind:

  • Write complete sentences that have proper grammar, spelling, and punctuation. Keep sentences and paragraphs short and direct.

  • Use the active voice. (For example, “The system shall do something,” not “Something shall happen.”)

  • Use terms consistently and as defined in the glossary. Watch out for synonyms and near-synonyms. The SRS is not a place to creatively vary your language in an attempt to keep the reader’s interest.

  • Decompose a vague top-level requirement into sufficient detail to clarify it and remove ambiguity.

  • State requirements in a consistent fashion, such as “The system shall” or “The user shall,” followed by an action verb, followed by the observable result. Specify the trigger condition or action that causes the system to perform the specified behavior. For example, “If the requested chemical is found in the chemical stockroom, the system shall display a list of all containers of the chemical that are currently in the stockroom.” You may use “must” as a synonym for “shall,” but avoid “should,” “may,” “might,” and similar words that don’t clarify whether the function is required.

  • When stating a requirement in the form “The user shall...,” identify the specific actor whenever possible (for example, “The Buyer shall...”).

  • Use lists, figures, graphs, and tables to present information visually. Readers glaze over when confronting a dense mass of turgid text.

  • Emphasize the most important bits of information. Techniques for emphasis include graphics, sequence (the first item is emphasized), repetition, use of white space, and use of visual contrast such as shading.

  • Ambiguous language leads to unverifiable requirements, so avoid using vague and subjective terms. Table below lists several such terms, along with some suggestions for how to remove the ambiguity.

    Ambiguous Terms to Avoid in Requirements Specifications
    Ambiguous Terms Ways to Improve Them
    acceptable, adequate

    Define what constitutes acceptability and how the system can judge this.

    as much as practicable

    Don’t leave it up to the developers to determine what’s practicable. Make it a TBD and set a date to find out

    at least, at a minimum, not more than, not to exceed

    Specify the minimum and maximum acceptable values.

    between

    Define whether the end points are included in the range.

    depends on

    Describe the nature of the dependency. Does another system provide input to this system, must other software be installed before your software can run, or does your system rely on another one to perform some calculations or services?

    efficient

    Define how efficiently the system uses resources, how quickly it performs specific operations, or how easy it is for people to use.

    fast, rapid

    Specify the minimum acceptable speed at which the system performs some action.

    flexible

    Describe the ways in which the system must change in response to changing conditions or business needs.

    improved, better, faster, superior

    Quantify how much better or faster constitutes adequate improvement in a specific functional area.

    including, including but not limited to, and so on, etc., such as The list of items should include all possibilities. Otherwise, it can’t be used for design or testing.
    maximize, minimize, optimize

    State the maximum and minimum acceptable values of some parameter.

    normally, ideally

    Also describe the system’s behavior under abnormal or non-ideal conditions.

    optionally

    Clarify whether this means a system choice, a user choice, or a developer choice.

    reasonable, when necessary, where appropriate Explain how to make this judgment.
    robust

    Define how the system is to handle exceptions and respond to unexpected operating conditions.

    seamless, transparent, graceful

    Translate the user’s expectations into specific observable product characteristics.

    several

    State how many, or provide the minimum and maximum bounds of a range.

    shouldn’t

    Try to state requirements as positives, describing what the system will do.

    state-of-the-art

    Define what this means.

    sufficient

    Specify how much of something constitutes sufficiency.

    support, enable

    Define exactly what functions the system will perform that constitute supporting some capability.

    user-friendly, simple, easy

    Describe system characteristics that will achieve the customer’s usage needs and usability expectations.

  •  

Write requirements specifically enough so that if the requirement is satisfied, the customer’s need will be met, but avoid unnecessarily constraining the design. Provide enough detail to reduce the risk of misunderstanding to an acceptable level, based on the development team’s knowledge and experience. If a developer can think of several ways to satisfy a requirement and all are acceptable, the specificity and detail are about right. Precisely stated requirements increase the chance of people receiving what they expect; less specific requirements give the developer more latitude for interpretation. If a developer who reviews the SRS isn’t clear on the customer’s intent, include additional information to reduce the risk of having to fix the product later.

Requirements authors often struggle to find the right level of granularity. A helpful guideline is to write individually testable requirements. If you can think of a small number of related test cases to verify that a requirement was correctly implemented, it’s probably at an appropriate level of detail. If the tests you envision are numerous and diverse, perhaps several requirements are lumped together that ought to be separated. Testable requirements have been proposed as a metric for software product size.

Write requirements at a consistent level of detail. I’ve seen requirement statements in the same SRS that varied widely in their scope. For instance, “The keystroke combination Ctrl+S shall be interpreted as File Save” and “The keystroke combination Ctrl+P shall be interpreted as File Print” were split out as separate requirements. However, “The product shall respond to editing directives entered by voice” describes an entire subsystem (or a product!), not a single functional requirement.

Avoid long narrative paragraphs that contain multiple requirements. Words such as “and,” “or,” and “also” in a requirement suggest that several requirements might have been combined. This doesn’t mean you can’t use “and” in a requirement; just check to see whether the conjunction is joining two parts of a single requirement or two separate requirements. Never use “and/or” in a requirement; it leaves the interpretation up to the reader. Words such as “unless” and “except” also indicate multiple requirements: “The buyer’s credit card on file shall be charged for payment, unless the credit card has expired.” Split this into two requirements for the two conditions of the credit card: expired and nonexpired.

Avoid stating requirements redundantly. Writing the same requirement in multiple places makes the document easier to read but harder to maintain. The multiple instances of the requirement all have to be modified at the same time, lest an inconsistency creep in. Cross-reference related items in the SRS to help keep them synchronized when making changes. Storing individual requirements just once in a requirements management tool or a database solves the redundancy problem and facilitates reuse of common requirements across multiple projects.

Think about the most effective way to represent each requirement.