Nov 22 2006

Authoring software requirements with a common vernacular

So it was that time again...  Time to write requirements for a new project.  Depending on your environment and the complexity of the anticipated solution this can be a really tedious piece of work.  As with most efforts such as this you need to try and create a common vernacular.  This is really crucial to ensuring you have requirements that are objective and agreeable. Here are a couple of examples.

Software Requirements Validation Criteria 

The requirements defined in the Software Requirements Specification (SRS) are evaluated with respect to the following criteria. This criterion is not intended to compete but is provided to clarify language usage between project stakeholders:

  • Correct. The SRS is correct if and only if every requirement stated therein represents something required of the system to be built.
  • Unambiguous. The SRS is unambiguous if and only if every requirement stated therein has only one interpretation.
  • Complete. The SRS is complete when it encompasses the following four qualities: 
    • Everything that the software is supposed to do is included in the SRS.
    • Definitions of the responses of the software to all classes of input data in all classes of situations are included.
    • All artifacts related to the requirement are properly identified and referenced.
    • No sections are marked as To Be Determined (TBD).
  • Verifiable. The SRS is verifiable if each requirement can be implicitly or explicitly tested. Every attempt should be made to minimize the number of implicitly tested requirements.
  • Consistency. The SRS is consistent if it uses the same terminology throughout.
  • Modifiable. The SRS should be written in such a way that requirements can be easily added, changed, and deleted. Establish criteria for how this will be accomplished in the Overview section of the SRS.
  • Externally Consistent. The SRS is externally consistent if and only if no documented requirement conflicts with the Statement of Work, System Requirements, or other projectspecific controlling documents.
  • Internally Consistent. The SRS is internally consistent if and only if no documented requirement conflicts with another documented requirement.
  • Traceable. The SRS should be traceable to the system/software specification which is provided by the customer. Each requirement shall identify its source.
  • Design-independent. The SRS cannot contain any design dependent requirements.
  • Concise. The SRS should contain only the necessary verbiage. Elimination of excess wording is critical for conciseness. Use of compound expressions (e.g. X and Y) shall also be avoided.

Best Practice Guidelines for Authoring Requirements

This project used the natural language specification for authoring requirements. The natural language approach requires only moderate training for those specifying the requirements and no, or very little, training for those who use the specification (e.g., software designers, programmers, testers, etc…). In general, each requirements statement shall address the following elements:

  • localization
  • entity
  • action
  • target
  • constraint

The following example requirement statement exhibits all five of the elements:

"When the user selects the 'Check-Out' document function on the Document Control Page, the Document Control Page shall launch the most recent document revision in its native application unless the Document Control Page is empty (i.e., has no document revisions)."

  • localization - When the user selects the 'Check-Out' document function on the Document Control Page
  • entity - the Document Control Page
  • action - launch
  • target - the most recent document revision in its native application
  • constraint - unless the Document Control Page is empty (i.e., has no documents revisions)

The following bullets provide some additional guidance for developing sound requirements statements:

  • Avoid weak phrases, such as:
    • as appropriate
    • may
    • if required
    • if practical
    • at a minimum
    • be able to
    • capable of
    • not limited to
    • as much as possible
  • Avoid imprecise words, such as:
    • simply
    • quickly
    • efficiently
    • friendly
    • timely
    • easy
    • normal
    • adequate
    • effective
  • Avoid generalities, such as:
    • large
    • many
    • most
    • near
  • Use the correct imperative verb:
    • shall - prescribes
    • will - describes
    • must - constrains
    • should - recommends
    • may - permits
    • can - indicates capacity/ability/possibility
  • Avoid compound statements such as ‘Shall do X and Y’ or ‘Shall include X, Y, Z’. This type of stated requirement should be split into separate requirements (Ex. Shall do X, Shall do Y, Shall include X, etc…) unless it is an all or nothing requirement
  • Do not use different words to refer to the same thing, for example:
    • computer screen and computer monitor
    • window frame and window pane 

Note: The use of the terms SHOULD and SHALL are guided by RFC 2119. If you find yourself writing requirements formally; or otherwise; this is worth a read.

Each statement should be accompanied by the source of the requirement and the date it was entered. If the source is a person (e.g., from a meeting, an informal conversation with the customer or customer representative, or a requirements elicitation session), the source should review the requirements statement once documented.

Tags: ,