A lot of books and blogs and experts tell us to use “The System shall…” when writing requirements. Read on to find out why that’s not a very good idea.
Ambiguity Is Bad
It is important that when you communicate requirements, you be unambiguous. That communication may happen through conversation or documentation, or some of each.
Conversations are most effective when you are face-to-face, and least effective when you’re talking to someone who is 8 to 12 hours out of sync with you. This is because conversations become infrequent. The time difference introduces a resistance into your product creation (requirements and design and implementation) process, because it decouples one of these areas from the other two. You can co-locate requirements and design with a remote implementation team, or you can have your design and implementation teams both working in a different location than your requirements team.
Remote teams introduce a latency in communication. When the teams are working with no (or very few) overlapping hours, this latency becomes very large. Each back-and-forth can take 24 hours instead of 15 minutes – that’s 1% as efficient!
The most effective ways that people have found to reduce the impact of this latency is through documentation – allowing artifacts to persist over time. Well written documents can capture understanding, will anticipate questions with correct answers, and will be unambiguous. 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?”
Language Barriers Can Hide Brambles
It is easy to acknowledge a language barrier when two people don’t share a common language. What is insidiously dangerous is when two people share a common language, but not really. There’s a clever joke – “England and America are two countries separated by a common language.” And it is very true. As a Texan, sometimes I feel that way about Americans from New England. Down here, a bubbler is an oil well that needs to be capped. Up there – it is a water fountain.
When you learn multiple languages, you translate (on the fly) into your original language. The one exception I’ve heard is if you start dreaming in the “new” language, you aren’t translating anymore. As our world gets smaller, and teams become more diverse, you become more likely to have someone on your team who is translating as part of communicating.
Translation is another source of ambiguity, both in conversation and in documentation. In conversation, you can practice active listening or look for other cues that give you an indication that what you said isn’t what she heard. In a document, either you are introducing ambiguity (causing another clarification cycle), or you are introducing an error in communication – imagine if the translation is “wrong.”
As dangerous and expensive as this can be in general, with a 1% efficient communication channel, it can kill your project.
Shall, Should and Must
In English, shall and must mean the same thing – something is mandatory. Should means, roughly “it would be a good idea.” In fact, should is such an ambiguous term, you should never use it in requirements. I’ve worked with teams that used a MoSCoW rating system before – every requirement was identified as one of “must”, “should”, “could” (don’t not do it), or “would be nice.” The problem with this approach is that the team is only accountable for the “must” requirements. At least in practice.
Personally, I’ve always disliked the word “shall” when writing requirements. First, not everyone considers “shall” to be a mandate – but generally people do. Second, I’ve always found the word shall to be too similar to should - which is a terribly ambiguous word in a requirement. Once I started working with global teams, often with “limited” sharing of a common language, I began to get that feeling that something isn’t right, that maybe shall would cause a problem. Surely must is ok.
This, I realize, is an opinion.
Translating Shall and Must
Around 5 am this morning I had a couple hours to kill and a disturbing notion of what would be “interesting.”
So I used Google’s translation service to translate shall and must into every supported language and back again.
When I was still programming, we often had to support import and export of data from our products. A great way to test the importer and exporter was to import data into the product, then export it back out (or vice versa) and compare the (twice) translated version with the original. If they were an exact match, both the importer and exporter worked. If not, there was a bug somewhere. We called this round-tripping. As an aside – this is a great way to do test-driven development of import and export functionality.
This morning, I round-tripped the words shall and must from English, through 41 different languages, and then back into English again. Here’s a table of the results (shall on the left, must on the right):
[Here are the facts about what happens when you translate shall from English into each of 41 other languages, and back to English again.
- In most languages (22/41) shall does not translate back into shall.
- Other round-trip results included: will, should, must, to be, point, has, going, and “I”
That confirmed my fears that shall was a dangerous word. What about must? I was not optimistic. I was also undercaffienated.
Here are the facts about what happens when you translate must from English into each of 41 other languages, and back to English again.
- For 100% of languages (41/41) must translates back into must.
OK, that’s pretty irrefutable data.
Conclusion
I don’t really care if you like the alliteration of saying “The system shall share secrets on sign-in”.
You need to use the word must when writing requirements to avoid ambiguity.
Latest Articles
Comments on all Articles
