Have you ever come across a software-requirements document? You may have noticed the following phrase being repeated many times for every single requirement: “The system shall…” Well, instead of those dots, you will see the requirement to be implemented.

I used to always think that each requirement has to be preceded by the phrase above. Sometimes I wondered, what if I wrote has to instead of shall? Would it be wrong? This is especially true because I learned that there is a template to be used for writing the requirements, and shall  is part of the game.

But we are talking about vagueness and storytelling in this series. If we follow such a template, could it be that what is planned for in this series may not work? Something scary, isn’t it?

If we want to complete our idea, it seems that we have to break from such a template. We have to stop shalling all the time. We will not shall  this time.

We don’t want to get you into mysterious terms. The bottom line is that it is not necessary to use such a template to express our requirements. It is not necessary to keep repeating, “The system shall…” X number of times.

Ben Rinzler hits the point when he mentions that using such a template is considered wordy, monotonous, and vague.

Scott Sehlhorst even mentioned it very clearly in his blog post titled, You Must Not Write “The System Shall…“ Scott then mentions that when communicating requirements, it is important to be unambiguous. It is very nice how he describes the effect of ambiguity, when he says: “The ambiguity part is key to improving team efficiency – every ambiguous statement introduces at best an extra back-and-forth (with possible delays), and at worst, an unpleasant surprise at the end of the project. When dealing with distributed teams, ambiguity in your documents is a killer. Your reader can’t pop his head over the cube wall and ask: ‘What exactly did you mean by this?'”

In his blog post, Scott wants to stress that one has to use must  instead of shall  in order to avoid ambiguity. But we want to go beyond that and say that we will not even use “The system…” phrase, with whatever verb is used afterward. We want to increase the readability of the requirements through storytelling and reduce their vagueness through fuzzy logic, as we will see in the coming posts in this series.

Roger Cauvin also talked about shall in his blog post “Limitations of “The system shall…“ He concludes: “It’s revealing that a product satisfying the first alleged ‘requirements’ specification (the series of ‘The product shall…’ statements) likely would fail miserably at addressing the user’s real needs. The real requirements are to mow the user’s lawn, and for it to be fast, easy, and comfortable for the user.”

Back to Ben Rinzler, who suggests using different verbs for stating the requirements instead of the shall  template, thus avoiding a repetitive sequence of words.

To sum up this article, let us take some examples from the medical-device software domain and try using the shall (Sh. prefix) template one time and the suggested way (NSh. prefix) the other time:

Sh.1. The system shall be able to look at incoming reports for unknown patient IDs.

NSh.1. The system filters unknown patient IDs from incoming reports.

Sh.2. The system shall alert physicians to high-level blood pressure using an integrated audio system.

NSh.2. The system makes a sound when high-level blood pressure occurs.

 Sh.3. The system shall provide a graphical user interface through which the physician can control the blood pressure threshold value for the alarm system.

NSh.3. The system sets a threshold value for the blood pressure alarm system.

Sh.4. The system shall enable the physician to set colors for the severity level of the blood pressure, such that green means normal, and red means severe.

NSh.4. The system shows a green color when the blood pressure level is normal and red when it is severe.

Which form do you think is better?

Photo credit: Raymond Bryson / Foter / CC BY