Requirements writing is one of the “classics” of Model-Based Design (1,2) and if you are, even in passing, part of the software development process then the next image is something you have heard 1E09 times.
If the “cost” of finding a bug goes up the later we find it, why are there still so many “bugs” in the requirements phase?
Now, in the times of COVID, because informal communication has declined, clear requirements take on even greater weight.
What is a requirement bug? A taxonomy
Before we talk about what needs to be in a requirements document, I want explain the common ways in which we write requirements incorrectly.
Pretty bugs (meet the beetle)
These are not “true” bugs (3), rather they are feature requests that do not have an impact on the product. For example, I worked on an infusion pump project about 7 years ago. One of the requirements was that the housing of the pump should be “gun metal gray.” Since I was helping with the software portion of this project, the color of the pump was not a relevant requirement.(4)
What made this requirement worse was there are some instances where the color of something is critical. For instance on that same pump there was the following requirement (roughly)
The emergency shut-off button shall be red in color. No other buttons on the device shall be red. The button shall be raised 1/4 inch from the panel and shall be in the lower right hand corner of the device. No other buttons shall be within 1 inch of the emergency shut off button.
Everything about that requirement was to ensure that when someone needed to “stop” the device right then and there, they would have the best chance to do it. By having another “color” requirement mixed into the engineering spec you give people the wrong impression.
Stale bugs
First, if you ever do an image search on “stale bread” I was shocked to see how many posts there were on “never throw away stale bread.” (5)
Second, what is a stale bug? A stale bug is any requirement that was not updated as the project changes; these could be called “orphaned” bugs.
In some cases the stale bugs represent parts of the project that has been moved passed. In this case they should be archived(6) and moved out of the general review process. In other cases it is that the maintenance portion of the requirements writing process has not been followed.
Communication breakdown bugs
At the edges of your kingdom(7) where you trade your precious knowledge, one word misspoken can lead to war.(8) These bugs are the result of different groups not communicating what their component needs and what it will deliver. These can be thought of as the “everyone knows that bug.” The one I remember best was with a transmission group who “knew” that rotational speed was in rads / second and the engine group who “knew” that it was in revolutions / second.
Wishy washy bugs (9)
A wishy washy bug is when, well you know, when the person who is, well the group, or you know the way in which it is put down, or not put down….
The above is an example of “wishy washy”. It is a requirement that does not meet the fundamental aspects of a requirement
- Unambiguous: the requirement can only be interpreted in one way
- Scoped: the requirement pertains to one aspect of the project
- Testable: the requirement can be verified to be achieved
What I’m expecting
I have written before about requirements, today I want to take a new focus, thinking about who will be using what you write.(10)
Before you write
As you set out to write a requirement, ask yourself the following questions (you will need to answer them all).
- Is this requirement needed: Not every task needs a requirement. Some “requirements” are simply notes of things that need to be done.
- Does this requirement depend on other requirements: If so you need to reference them
- Can this be written without project specific jargon: If not do you have a “dictionary” to explain the jargon?(11)
- Is this one requirement or multiple: Don’t try and fit everything in one requirement! (At the same time don’t make every detail its own requirement.)
- What supporting material would make the requirement clear: A picture can be worth 1,000 words; a free body diagram or plot is worth 1,000,000.
As you write
As you write you need to keep thinking “am I answering the questions from step 1?” Beyond that, are you
- Sticking to the scope of your requirement?
- Writing in an unambiguous format?
- Writing in a testable fashion?
- Avoiding the soap suds of wishy-washy writing?(12)
After you write; feedback and sign off
Before a requirement is accepted into the workflow there should be a formal sign-off step. If the person signing off looks at it for a minute and says “yeah that makes sense” either they are a subject matter expert or they have not really reviewed the requirement. This happens far too often.
When you select your reviewer they should
- Have knowledge of the area of the requirement and (preferably) the areas impacted by the requirement
- Have a level of responsibility for the impact if the requirement is incorrect
- Have an understanding of the test-ability of the area
The last item is key. A requirement can be written in such a fashion that to an outsider it appears testable but to someone who works on the project they would know it could not be tested as written. For example; I worked on a bio-reactor hardware in the loop project a few years ago. One of the requirements which was critical was “the core temperature of the bio reactor shall never exceed 87 deg C.” When I read this I thought, great, this is a clear requirement, except there was no measurement device to check the core temperature.(13)
Wrapping it up
Writing good requirements takes time, however think of them as a gift to the developer and yourself; or perhaps think of it as a gift to the developer and a “gift wish list” to yourself.
Footnotes
- In reality all areas of work have “requirements documents.” In recent years I have started thinking of requirements documents as “contracts” that we negotiate between developers and the end users.
- For the image “100 best classic movies” I find the statement problematic; above a given level each “movie” is a distinct thing, e.g. you could say “the best murder mystery” or “the best road trip movie” but “best classics” seems redundant.
- Beetles are members of the order Coeloptera which do fall into the insect kingdom, so yes, they (beetles) are bugs, but pretty bugs are not bugs.
- On the other hand, having this in the fabrication spec would been the logical location.
- On stale bread, if you were using a good quality bread to start with then I can see some uses of the stale bread: bread crumbs for “breading,” croutons, bread pudding or possibly French toast.
- Never get rid of old requirements, sometimes the “stale” bug can come back to life and if you have to reinvent it, then it is redundant work.
- In this case “Kingdom” equals component
- And in this case “war” means really long arguments about whose fault it is when the integration fails.
- I honestly have no idea what could be going on in that world, on the one hand singing cows look like they would be fun, on the other hand I think the goose would be the better horn player.
- In about 50% of the cases, the requirements are written by the same person who will implement the requirement (often after they have created the object).
- I should be clear, often using project specific terminology is a good thing, e.g. it simplifies the writing process; just be sure that everyone agrees on the terminology before you use it.
- Why yes, this is a repeat of the list from earlier on, these tests cannot be repeated enough.
- Keep in scope
- Write unambiguously
- Write testable requirements (12)
- We were able to take measurements at the boundaries of the container and we then used heat transfer coefficients to determine (approximately) what the core temperature would have been. It was a fun example of both thermodynamics and boundary layer theory.