The definition of a product requirement is “Something the product must do or a quality that the product must have.” Alternatively, more formally, “A requirement statement is the result of a formal transformation of one or more needs into an agreed-to obligation for an entity to perform some function or possess some quality (within specified constraints).”
At ArgonDigital, we believe that a good form for a text-based product requirement is – The [Noun] shall [Verb] […what…], [quantifier]. We advocate this form to make clear the product to which the requirement applies, who/what is responsible, and make it easy to check for the correct hierarchical level.
That said, I often get the question “If a requirement clearly addresses a property, quality, or performance characteristic of the product, why not let the noun be the property, quality, or characteristic of the product?”
For example,
Instead of: “The System mass shall be less than 100 kilograms.”
We write: “The System shall have mass of less than 100 kilograms.”
or
Instead of: “The System field-of-view (FOV) shall include the entire Earth disk.”
We write: “The System shall have a field-of-view (FOV) that includes the entire Earth disk.”
When I first read the alternative method of writing the requirement statement with the noun being the property, quality or characteristic of the product, I thought, hey no problem. But upon further reflection, I concluded that there are several reasons for staying with the “who shall do what” format where the subject (without qualifiers) of the requirement is at the beginning of the sentence followed by shall and a verb that indicates the action the subject is expected to do and then a verifiable qualifier that defines the end result of the action. These reasons for using this format include:
- There is a very distinctive single “Who” without adding other qualifiers to it. This statement of “who” helps with communications and helps the stakeholders think in a certain way, clearly understanding the entity to which the requirement applies. This has long since been a proven best practice for avoiding misinterpretation.
- The “who shall do what” format also helps to determine if the requirement is at the right level. For example: “The system resistor shall be 10 ohms.” vs. “The System shall have a 10 ohm resistor.” The first example may make sense in general layman terms, however, it doesn’t have one thinking in terms of levels, while the second example quickly shows this is a ridiculous requirement for the System level. Levels are an important issue and staying with the conventional active voice form results in the noun indicating level, which helps keep the requirements at the appropriate level. Requirements at the wrong level will cascade into other issues with allocation and traceability. If these concepts are broken, then the bottoms-up integration, verification, and validation activities will be broken as well.
- Another issue is implementation. The resistor example above is obviously not a system level requirement, and thus looks like implementation. As with all implementation at the wrong level, the question “why?” the implementation is not stated. By stating at the system level there has to be a 10 ohm resister, the “why” doesn’t get addressed and doesn’t get allocated properly and thus there is a high risk that the real intent doesn’t get implemented.
In the case where you start working on a project that already has a set of requirements, and you bring up issues with the above concepts, it may be hard to convince your team that the requirements need to be rewritten. This situation is especially true when the engineering team feels that they understand what is meant with the requirements in their present form.
The sad thing is that this viewpoint forces the design team to ignore the poorly written set of requirements and do the “right” thing to get the system to work properly. While this seat-of-the-pants approach can result in the correct system, verification of the poorly written requirements will be problematic (even though validation will probably work out OK.) “Pay me now or pay me later, if later, pay me a lot more!” It would be cheaper to fix the poorly written requirements upfront rather than wait until verification…………
More on the formal definition of a requirement
Concerning the more formal definition of a requirement “A requirement statement is the result of a formal transformation of one or more needs into an agreed-to obligation for an entity to perform some function or possess some quality (within specified constraints).
While this is a more complex statement, the two thoughts in red text are often overlooked when writing requirements. Not understanding these two thoughts leads to more issues. I see this a lot with software development teams, especially the “Agile” crowd. They try to use user stories, use cases, etc. as requirements without doing the transformation. [For more details on transformation see my blog: “Going from system concepts to requirements – Part 1“]. Some don’t even want there to be any requirements to agree to!! This in turn results in a lot of problems and failed projects!!
The other phrase on agreement is also critical as an agreed-to set of requirements forms a contract between the customer and the implementers. The point of the more formal definition is to make these points clear and to back up the points by stating the characteristics of well formed requirements. For the requirements to be well formed (no matter the form they are expressed in – textual or otherwise) they need to have these characteristics.
Characteristics of individual requirements:
Formal transformation: Necessary, singular, conforming, appropriate to level, correct.
Agreed-to obligation: unambiguous, complete, feasible, verifiable.
Characteristics of a set of requirements:
Formal transformation: Consistent, balanced, complete
Agreed-to obligation: comprehensible, feasible, able to be validated, bounded.
With this thought in mind, it is easier to make the case for the “whom shall do what” form rather than the alternate form discussed earlier. Note, if the alternate form can be shown to have these characteristics, then I don’t see a problem using either form. In both cases, go through the proposed set of characteristics to see which form is better. Not meeting any of these characteristics will result in problems.
As we have discussed the alternate form is questionable when it comes to “appropriate to level”. Implementation falls within this characteristic. Also “conforming” is an issue in that the alternate form violates the rules for writing text-based requirements that is most frequently advocated.
In conclusion, while alternate forms may seem on the surface to be acceptable, there are underlying issues that can result. To help avoid these issues, we highly recommend you stay with “The [Noun] shall [Verb] […what…], [quantifier].” form.
Comments to this blog are welcome.
If you have any other topics you would like addressed in our blog, feel free to let us know via our “Ask the Experts” page and we will do our best to provide a timely response.
