Guidelines for good requirements

Clarity is the foundation of the IBM® Engineering Requirements Quality Assistant (RQA) business logic. Good requirements must be clear and verifiable because they underpin communication between multiple parties and are the basis for contracts, designs, project plans, and other product-management and engineering activities.

The guidelines that RQA and IBM Watson® use to assess requirements are designed to be consistent with industry standards such as the Guide for Writing Requirements published by the International Council on Systems Engineering (INCOSE).

The RQA guidelines are based on these concepts:

• Write simple requirements: The guidelines dissuade requirement authors from combining two or more requirements into one statement, which is known as a compound requirement. Each requirement should have its own engineering and verification path, because compound requirements with multiple elements are difficult to track and manage. RQA identifies possible compound requirements by flagging conjunctions such as and and but.
• Write complete requirements: Requirements are expressed in natural language because they are read by humans, not machines. To conform to the foundational principles of natural language and what constitutes a complete statement, each requirement should include an actor (who or what performs the action), an action, and the object of the action.
• Be practical: The guidelines ensure that requirements are practically verifiable. For example, RQA reviews requirements for quantitative goals and, if found, determines whether those goals include tolerance ranges. The rationale for enforcing ranges is that no system or machine in the real world can consistently conform 100% with a target. A degree of error always exists, and requirement authors must specify the acceptable degree.
• Be as specific as possible: The guidelines encourage authors to think about a requirement in detail, especially boundary conditions. The tool flags words and phrases such as any, all, minimum, several, sufficient, flexible, user-friendly, minimal, or best practices because they lack specificity.
  The following requirements are vague. The terms flexible, user-friendly, and minimal must be defined.

  • The user interface shall be flexible.
  • The user interface shall be user-friendly.
  • The user interface shall require minimal training.
  RQA flags the following requirement:

  • The engine shall confirm to best practices in order to control polluting effluents.

  This requirement is flagged because best practices is open to subjective interpretation. To be specific, reference a measurable level or an industry standard that describes a best practice:

  • The engine shall limit polluting effluents in accordance with Clause IV of Standard XYZ of the Government of the United States.
• Reinforce accountability: Sometimes requirement statements contain phrases such as where possible, if necessary, and so on. These types of phrases are called escape clauses because the people who implement requirements can use those phrases to avoid implementing complex elements. Similarly, the guidelines emphasize that you should differentiate words such as shall, could, and would to indicate mandatory versus optional requirements. For example, your organization might use shall to identify requirements that are contractual commitments. RQA identifies phrases or words that could deflect accountability.
• Use correct units and their abbreviations: Sometimes, requirement statements include the measuring units or their abbreviations. Make sure that you write them as per the International System of Units (SI) standard.