Pedro Carolino wrote the infamous English As She Is Spoke in 1855 to help his fellow Portuguese speak English, but he didn’t know any English at all. So, he used a Portuguese to French to English translation chain to generate what is now a timeless presentation of language. Writing requirements that are easily understood by both the author and those responsible for satisfying the requirements may feel at times like translating between different languages.
After considering the general utility of requirements, the distinction between requirements and design, and how to establish a practical hierarchy of design information progressing from general to specific, this third installment of our discourse on requirements is about “requirements language” itself.
Previous blogs on requirements can be found here:
Engineers who write requirements are taught early and often about language constructs such as “shall” or “must” versus “should” or “may.” They are regaled with reminders of “characteristics of robust requirements” such as from ISO 26262-8:2018 Clause 6.4.2.4. Despite these efforts, however, requirements often fall short of the goal of clearly communicating the intent of a product. This blog discusses some practices to help generate clear, robust requirements that satisfy the “textbook” characteristics we haven’t discussed in the previous blogs.
Requirements should be understandable by as large an audience as possible. To this end, “requirements-ese¹” should be avoided as much as possible. We provide basic guidance for improving comprehensibility, removing ambiguity, facilitating test development, and making requirements a useful tool throughout the development process.
1. Use active voice instead of passive voice
This clearly communicates the “actor” or element that is responsible for the content of the requirement. Consider a common statement “The Error message shall be sent if the data stream contains an invalid value.” Ambiguity primarily arises from the question “who or what sends the message?” Instead, phrase requirements as “Control Module A shall set the Error field in message Foo to indicate an invalid value when the Bar data stream has an invalid checksum.”
2. Use positive formulation instead of negative
An initial requirement might be drafted such as “The battery shall never catch on fire.” This negative formulation using shall never, or other forms such as shall not, are unbounded, difficult to verify or implement statements. Formulating requirements that say what a product shall do or shall be is a more feasible, achievable statement than stating what a product shall not do or be. In a purposely hyperbolic example, if a manufacturer creates a device that bakes cookies, does it satisfy the requirement “the battery shall never catch on fire?”
A much more robust formulation for this example would be “The Battery Monitor shall open the contactors if any cell exceeds <threshold> temperature.” This has a bounded test criteria and a cookie-baking machine, regardless of how tasty the treats may be, would not satisfy such a requirement.
3. Maintain scope of responsibility / keep locality of information
It is possible to create active-voice, positive-sense requirements that are still difficult to verify or perhaps don’t quite define the desired product behavior. Consider a common requirement for a control module: “The Module shall receive the Status message from the actuator.” At first glance this appears to be a robust requirement. However – would the module satisfy this requirement if the actuator fails to send the status message? Ideally, we want a requirement that the Module can satisfy “on its own.” To that end, consider this alternative wording: “The Module shall <perform action> when the Status message is present on comms bus A.” Note the improvements: Our module can be tested regardless of what is sending the message. The module’s behavior is predicated on the well-defined state of a message being present on a specific bus. This means the success of the module in question does not depend on the ability of some other system component to perform its functions. This helps improve atomicity and make verification simpler.
4. Don’t use anthropomorphic language
Requirements are often worded with terms that have connotation associated with human behavior instead of rigorous meaning which can introduce ambiguity. “The device shall provide…,” “the product shall avoid…,” and “the product shall have the capability to…” are common phrases that hint at anthropomorphic phrasing that hides the true intent of a system.
| Construct | Alternative | Rationale/Example |
|---|---|---|
| shall provide | shall have / shall be | “Providing” is an ambiguous, informal verb. “Having” or “being” is a much more rigorous, verifiable statement. “The software shall provide an API” could be “The software shall have an API.” Existence is verifiable through simple inspection, where “providing” is a more abstract construct. |
| shall avoid | change to positive formulation | “Avoiding” is a very difficult phrase to verify and can be challenging to test. Consider “The vehicle shall avoid collisions.” This is a broad statement which can generally only be evaluated after the fact, on in-field performance. A statement such as “The vehicle shall apply brakes if approaching an obstacle closer than <distance> at a speed more than <speed>” is a requirement which can be verified at design time. |
| shall have the capability… | shall have / shall <do> | We don’t want a device to “have the ability” to do something; we want the device to do that thing. The requirement should just state the desired characteristic or functionality. For example, contrast “The module shall have the ability to automatically lock the door” with “The module shall send a signal to lock the door when <condition>.” |
5. Keep requirements self-contained
A requirement should be a complete action without having to refer to other requirements. This is best illustrated by a counterexample: “When the Module measures >12V on input A, it shall carry out the sequence of tasks in requirement 36.” The first part of this requirement is active voice, it’s specific, and is technical. However, this requirement cannot “pass” verification unless all the steps in requirement 36 also pass. This means the requirement is not atomic. The solution to this pitfall is related to the earlier blogs: typically, this structure suggests the details in “requirement 36” in this case are design information, not requirement information. The requirement formulation could instead be “When the Module measures >12V on input A, it shall <achieve the goal of the steps in ‘requirement 36’>.” That is – state the desired observable state, not a requirement to go reference.
One caveat: when a requirement is referencing an external standard or regulation this external-reference style might be unavoidable.
6. State what is required, not optional
Requirements should only be issued if the content is indeed actually required. This seemingly obvious statement often causes much debate, especially in contexts where there are discussions about “shall” requirements versus “should” requirements. If a behavior is not necessary, it shouldn’t be a requirement at all! Otherwise, how is it verified?
An alternative approach is to re-phrase the “optional” requirement into an actual requirement, often using a concept of configurability. Managing the overhead of “optional” requirements can be a challenge for both project managers and implementers. It is better to simply draft the requirement as a “shall” requirement and then prioritize/schedule it for a particular release instead of making it “optional.” For example, instead of “The device may play a sound when the trigger is detected,” a better requirement is “The device shall play a sound when the trigger is detected if the configuration value ‘enable alert sounds’ is asserted.” Put another way – optionality should be done by scheduling and prioritization, not through having requirements that are satisfied without action. Therefore, we recommend against using “may” or “should” in technical requirements. Statements including “may” and “should” do have their place, however, in guidance documentation, business goals, and other non-technical contexts where striving toward an ideal is desired but does not warrant forcing a design iteration, stop-shipment, or release with formal deviation.
7. Use parameters instead of magic numbers
It is very common to include exact numbers in a requirement. Even in some examples above we utilized this structure – for example “The module shall <perform an action> when the voltage on input A is >12V.” Instead of a specific value, it can be beneficial to use a named parameter. This way, if the parameter is used by multiple requirements, they can all be “changed” instantly and in coordinated manner by simply redefining the value of the parameter. So, the above requirement might be “The module shall <perform an action> when the voltage on input A is at or above the configurable {Threshold Voltage A}.” Although this does contradict the principle listed above to keep information self-contained within a requirement, the tradeoff in this case is worth the external reference in terms of flexibility and maintenance.
8. Words may not be enough
While prose is a powerful tool for communicating ideas, sometimes words are not enough, and some other representation is warranted. Representations like state machines and tables are often used to present complex information. The challenge in using these formats is in ensuring a consistent interpretation of the semantics.
State Machines
A state machine is a concise way to represent transitions between behavior states. State machines can be interpreted as requirements without using prose language, so long as the transitions are identified for traceability. In the example state machine, for instance, the transition labeled [id 3] should be interpreted as the requirements “The state machine shall perform <action 2> and transition from state 2 to state 1 when <condition 2> is detected.” So long as an organization has a document defining the standard way to interpret state machines, there is no need to write this text sentence for each transition. State machines are often augmented with some text requirements such as requirements on how often the conditions are to be evaluated.
Tables
Tables are a concise format for specifying attribute or performance requirements which is very similar across a large number of system elements. This is extremely useful for hardware specifications and communications specifications. This format avoids repetitive wording and presents data in an easy to reference location. As with state machines, organizations using tables to contain requirement data should provide documentation on how to interpret data. In the example below, each row of the table should be interpreted as a set of requirements. The textual interpretation might be something like:
“[comms-02] Module A shall transmit message 2 with ID 0x4840 on Bus A within 50ms of receiving Message P.”
| Req. ID | Message Name | Message ID | Bus(es) | Transmitter | Transmit |
|---|---|---|---|---|---|
| [comms-01] | Message 1 | 0x4830 | Bus A | Module A | periodic: 100 ms |
| [comms-02] | Message 2 | 0x4840 | Bus A | Module A | within 50ms of receiving Message P |
| [comms-37] | Message P | 0x1830 | Bus A | Module B | within 50ms of detecting fault 47 |
9. Taming Time
Describing temporal relationships between requirements is a particular challenge. This is due to a combination of the open-ended nature of time and avoiding creating interdependent requirements or a single very complicated requirement. Some of the difficulty can be removed by avoiding codifying design as requirements – this is closely related to the comments above regarding self-contained requirements. A reliable approach to addressing time is to use constructs that refer to specific events rather than requirements and using terms that bound a behavior within a given time after an occurrence of said event. The table below describes some of these patterns.
| Phrase | Usage Example |
|---|---|
| Immediately After | “… shall <act> immediately after <event> …” imposes a constraint that the action is the immediate subsequent behavior after some event. |
| Within <time> After |
“… shall <act> within <x time> after <event> …” imposes a constraint that the action follows some other event but can tolerate some bounded delay after the triggering event. Special consideration: Due to the potential delay from the event to the action, especially for events which may occur frequently, it may be necessary to clarify which event. For example: – “after the most recent occurrence of <event>”: This is used to act after the most recent event, which acts as a buffer – the arrival of many events in a short interval delays the action. – “after the first occurrence of <event> since <qualifier>”: This is used to act on an event and discard events that occur quickly after the triggering event. Use this pattern when many events occurring in a short interval should not delay an action. – “… after every occurrence of <event>”: This is used to ensure the action occurs for every event that occurs – none should be skipped or dropped. This is the most strict form and may constrain which designs can satisfy the requirement. |
| Once every <interval> | “… shall <act> once every <min s to max s>” is a periodic event, where the action is expected to occur once every time interval is completed. The min/max specifies allowed jitter between the events. |
Our hope is that the examples above give your team the language tools to de-mystify “requirements language” and help make more robust, clear, easily verifiable, and easy-to-maintain requirements. The above guidelines should be taken as heuristics which can be applied during requirements drafting and review activities. Dealing with active voice, using positive formulation, maintaining locality of information, avoiding anthropomorphism, requiring only what is needed, parameterization, graphical and tabular presentation, and precision timing words are all ways to improve the clarity and utility of your requirements. To mix a few pop-culture references: after all, unlike roses, requirements with any other words probably aren’t the requirements you’re looking for².
Looking to strengthen your team’s expertise in creating clear, effective requirements? Explore our full range of training courses here.
References
¹ Playing on the term “legalese”; “requirements-ese” is language structure and style often seen only in the context of technical requirements.
² Shakespeare’s “A rose by any other name…”; Star Wars “These aren’t the droids we’re looking for”
