It is well documented that the most cost effective point to find a bug is during the requirements definition phase.  Yet companies struggle to enforce good requirement writing guidelines and to maintain the requirements throughout the development lifecycle.  Why?

Requirements hierarchy

When writing requirements the first thing to understand is that there is a hierarchy to requirements.  There are “top level” and “derived” requirements(1).  In some instances, there are test requirements.

• Top-level requirements:  Can be characterized as “end user requirements.”  They describe the top-level interactions of the device.
• Derived requirements: They decompose the top-level requirements into individually testable statements.  Depending on the complexity of the device there may be two layers of derived requirements.
• Test requirements: Test level requirements are a special case of the derived requirements.  For some requirements tracking tools decomposing the derived requirements into individual test requirements for tracking is advantageous.

Guidelines for writing requirements

There are 5 fundamental guidelines for writing clear requirements.

1. Write atomic requirements: Requirements should have only one requirement per item.
2. Use action language:  Each requirement must contain a subject (user/system) and a predicate (intended result, action or condition).
3. Describe what the system will do: Avoid describing how the system will do something. Only discuss what the system will do.
4. Use consistent language: The requirement documents should use consistent language.  A definition document should be written and followed.
5. Write testable requirements:  The requirements should be written in a testable fashion.

A further best practice is to perform design reviews on requirements early on in the writing process.  This ensures that people are following these guidelines.

Maintaining requirements

There are two ways in which requirements change.  First changes to the top level requirements push changes down to the derived requirements(2).  In this case affected derived requirements should be updated.  This is helped if there is a mapping document between the top-level and derived requirements.

The second way in which requirements change is due to limitations or errors found during the design and analysis phase.  These are found when the tests, based on the requirements, fail.  At this point in time, it is up to the test engineer and developer to determine if the error is in the implementation or the requirement. If the error is in the requirement then the requirement should be updated.  Note, using bug tracking software to link tests back to the status of requirements will simplify this process.

Establish requirements traceability

Most Model-Based Design software allows you to establish links between the models and the requirements.  Using these links can help automate and enforce good requirements maintenance habits.  A Simulink example can be found through this link.

Final thoughts

This blog post serves as an introduction to requirements management. Additional thoughts and resources will be laid out in future posts.

Footnotes

(1) The terms “top level” and derived requirements vary from industry to industry; however, the core concept is consistent across industries.
(2) Ideally, any changes in the top level requirements take place early in the design and analysis phase to reduce impacts on cost and time.