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.
I think the finer distinctions among “shall”, “must”, and “should” are not a significant issue.
The real issue with “the system shall” is that it forces requirements into a rigid grammatical structure that doesn’t efficiently or clearly communicate the problems to be solved and what it would mean to solve them.
I have suggested black box use cases as a format that in most cases better communicates the conditions under which the stakeholders’ problems would be solved (i.e. the requirements).
For Scrum folks, user stories with acceptance criteria are an alternative to black box use cases.
@Roger [1] – I agree with your point strategically – in terms of articulating what problems a product must solve for a customer, use cases (and vision/scope + goals) are critical. However, I still find value in writing atomic “The System must…” statements when writing a specification, especially when engaging a third-party team to do the implementation work. A user centric approach is (in my opinion) the approach to framing the goals of a product that is most likely to succeed in a great product being developed. However, when that framing of goals is insufficiently detailed (such that “any” solution would be acceptable), you need to go into more detail.
I believe almost all of the problems with the “rigid grammatical structure” requirements we have seen come from having a lack of context. The goals have to be identified. The user-activities by which those goals will be achieved have to be identified. And the atomic statements do add value within that context.
Language is a real issue. I’ve recently been working on a European team where English is the project language but the team come from Spain, Holland, Belgium and the Channel Islands.
In general, English as a second language wasn’t a problem as everyone is fluent or near fluent.
However, we had a long conversation to uncover some confusion withn our Spanish stakeholder when using the word ‘bound’. It was used in terms of ‘when the payment is bound for Spain’.
Our Spanish stakeholder understood this to be meaning bound as in ‘boundary’ or limit.
It took a good five minutes to identify the confusion and rectify it.
Lessons learnt – use simple English!
What would have happened if it had been agreed with poor understanding of the requirement?
@Alex – thanks for commenting – that is a great anecdote. It also touches on a couple articles I wrote ages ago: Symbolism and Communication and Active Listening and Cultural Cues – When ‘No’ Means ‘Yes’.
In Italian “shall” does not exist. Its translation depends on the context because “shall” can have slightly different meanings. It is often translated with “must” (dovere), but other times more words are needed to translate “shall”. As a non native English speaker, sometimes I find difficult to understand when to use “shall” instead of “must” or “will” because we don’t have a word corresponding to “shall” in Italian. In conclusion I agree with you: “shall” is ambiguous. We have the same problem in Italian with the future tense because it has more than one meaning dependent on the context: “it’s going to…”, “it will…”, “it must…”, “it should…”. For this reason, when I write requirements in Italian, I prefer to use a modal verb (must, should, could) instead of the future. Cheers.
@Marco – thanks for the great explanation. Language skills (other than programming) are something I never successfully developed. I’m stuck with just English (and pascal, and C#, and Forth, and….). Your explanation of how this manifests in Italian is particularly interesting.
As an advocate of good communication, I found this very interesting. It’s the little things like this that can sometimes make huge differences. Thanks for taking the time to look into this.
To Roger’s point: “The real issue with “the system shall†is that it forces requirements into a rigid grammatical structure that doesn’t efficiently or clearly communicate the problems to be solved and what it would mean to solve them.”…..I’d have to say that this is the whole point. The communication of the requirement should not rely on a word like shall or must, but rather on effective use of proper verbiage to state the requirement clearly. Shall/must is nothing more than a qualifier to describe importance, yet can be important in the eyes of the stakeholders
@DougGtheBA – thanks! I do believe that there’s value in the clarity of the language, and I think Roger also has a point about the importance of providing context for requirements and having a user-centric approach to defining value.
DougGtheBA, I don’t think you fully understood my point. Forcing a certain grammatical structure has more impact than simple word choice. Choosing whether to use “shall” or “must” is not very important if the very notion of a series of atomic sentences to represent requirements is fundamentally misguided.
@Roger [5]. I Agree that a series of statements without context is a big problem. But even once you do provide context (with traceability to goals and use cases), you still need to use “must” instead of “shall” to reduce ambiguity.
And thanks again for contributing significantly to this (and other) discussions here!
I found this article and discussion very interesting as well.
I have worked with managers and project managers who have very strong opinions on this topic in very different directions. My first manager enforced use of a variety of MoSCoW.
My current manager, however, strongly discourages the use of “the system” and the words “must” or “shall”. She also encourages use of the present tense since the requirements should describe the system when it is complete. The result ends up somewhere in between traditional requirements and use cases.
For example:
Printed reports include the date and time the report is printed.
Prior to printing a report, the user is offered the opportunity to select from the following options to sort the data presented in the report:…
(Note: Reference to the system is not always avoidable because sometimes you have to distinguish whether you are talking about something within the boundary of the system versus other aspects such as integration code with other systems.)
I am interested in opinions on this latter approach to requirements sentence structure, especially in light of the above article.
@Rachel – thanks! I really appreciate you joining in on the discussion! I’m interested to hear what other people think too, but personally, I believe “Printed reports must include the date…” is much more explicit than not using “must.”
There is an interesting stylistic difference between the passive, declarative statements about outputs (the report must have…) versus active statements about the system (the system must produce reports that…) or about the user (the user must be able to produce reports with…). When I wrote about writing style in requirements a couple years ago, I had not seen this approach. I definitely need to update that article to include this approach (and replace “shall” with “must”).
Thanks for pointing out a different perspective on this important point – I hadn’t put two and two together on how the phrasing is both limiting and subjective. Personally, I prefer more direct language, and I’ve found that teams I’ve worked with have really responded with more pointed, direct questions that help move the project forward quickly.
@Brooke – thanks! Yes, I’ve had the same experience when working with good developers – explicit, unambiguous statements tend to evoke more passionate responses!
Very interesting article. One phrase I find often used in requirements specification is…'[The system should] provide the ability to’…with people then trying to make the requirements fit that construct.
I did find the sentence “In fact, should is such an ambiguous term, you should never use it in requirements” amusing.
@David Smith – thanks, didn’t know if that one would come through or not. :) I did intentionally mean “it would be good, but you don’t have to do it – I won’t hunt you down :).
It’s funny to read this, especially as my team never writes requirements anymore, just user stories and acceptance criteria.
That being said, I learned “The system shall…” and by golly, I like it that way! But since I’ve been in this discussion a number of times and that argument is pretty worthless, let me tell you how I rationalize my usage of shall.
First, I like the formality of the phrase (though I can understand where others may not feel the same).
Second, it’s tradition.
Third, it’s not a common phrase in everyday language.
Fourth, it is incredibly easy to set a benchmark of understanding on projects that this phrase means “it’s a requirement.”
The truth of the matter, for me at least, is I want a very clear understanding of what is, and what is not, a requirement. This phrase, due to it’s uncommon usage, tradition, formality, and expectation setting does just that.
And when I use this phrase everyone on my team knows exactly what I’m talking about. There is no ambiguity. We all know that the words following “The system shall” become the objective we are building towards. Because we all have a common expectation.
We made the expectation clear. Where’s the debate?
Which leads me to my final point. A forced grammatical structure needs to serve the goal of communication rather than some boss’ whim (even if that boss is me). **The whole point of requirements is communication;** whether across time zones, departmental boundaries, or a murky future when we want to know why those jerks in the past coded it this way.
If you get better communication through pictures, charts, flows, tables, stories, stick-figures, or mind-melds, then do that. It’s all about the communication.
And for my money–when I have to write out the requirements–“the system shall” removes ambiguity, so I shall use the phrase.
@Jeffrey – hey, long time no see – welcome back! When you’re writing acceptance criteria, I guess you’re saying “The system shall respond in X seconds?” Regardless of the form the documentation is in, the shall/must debate is relevant.
Your point that communication is the key point is exactly correct. That’s what this is all about. If your team always interprets “shall” in the same way (presumably as an equivalent term to “must”), then it works for you. How would your team interpret “should?” That was the point I was trying to make when doing all of the translation-research. Even when you write “shall” (with the intention-equivalent of “must”), the person reading your requirements may be reading “should.” And that person may therefore interpret a different intention than the one you intended.
Interesting stuff, Scott. I’ve had my share of issues with requirement focus words, but none that have caused me to be up by 5am thinking about them! :) Anyway, here’s my $.02 to add –
Shall, must, will, can, etc. might be ambiguous if you’re going by the dictionary definition, but I thought most folks used the definitions in the IEEE standard for their use in a requirements context (See http://standards.ieee.org/guides/style/section5.html). All the organizations I’ve worked with have used those definitions except one, and that group defined the terms in the document glossary to avoid ambiguity.
Some are willing to accept the “rigid grammatical structure” (and that’s exactly what it is) in return for the consistency and precision that using a widely used and familiar standard brings (for what it’s worth, use of “System shall” is a recommended practice according to IEEE 830-1998). For all its faults, it is a very familiar and easy-to-use convention.
I have no problem with “system shall” or any other convention for specifying requirements as long as the folks that are going to use them to design, code and test the system understand them. There are lots of “good practices” for specifying requirements, what’s most important is to agree to what works best for your organization and go with it.
The only things that I’ve found that “must” be present in a good requirement are the following: a subject, a capability, and ideally a constraint or acceptance criterion. Other than that, whether you use shall, must, user stories or use cases in plain language or whatever you choose – it’s all a matter of preference.
What I don’t like about “The system shall,” is the fact that it is inefficient. It seems like if all your requirements start with the same 3 words, you could just as easily lop it off as waste. Really, what’s the value of “the system shall” repeated in every requirement? Think of all the keystrokes or ctrl+c & ctrl+v’s! Think of all the paper! :)
Anyway, great conversation, Scott. Thanks for doing the research. The comments have been a treat, too. It’s the practical, every day stuff that I love to see dialog on. There really are lots of good practices, and I’ve learned about and eventually adopted more than one as a result of dialogs like this one.
@Jonathan – In my defense, I was up at 4am because I was taking my wife to the airport. I just found myself with some free time at 5am :).
Thanks for the link to the IEEE standard. It is unambiguous in explanation. Personally, I am not going to “deprecate” the use of the word “must.” There are too many examples of “shall” being translated as “should” to justify using “shall” just because of the IEEE standard. Ten years ago, I was only working with teams that were native English speakers – and for those teams, I think the standard would be fine. My (fact-supported) opinion is that the standard should restore the use of “must” and deprecate the use of “shall” precisely because of translation-induced ambiguity, in acknowledgment of the growing pervasiveness of multi-lingual teams.
Funny point about the DRY (don’t-repeat-yourself) critique of “The System…” There’s just no clear answer for that. I’ve tried to start bulleted lists with “The System must:” and then leave that phrase out the individual bullets. Each time I do, I end up re-inserting it, because of the risk of a single requirement being managed, implemented, or interpreted outside of the context of the list. This is especially true when writing acceptance criteria, and when managing requirements within a repository, where the list-context is completely lost (or unreasonable to assume).
I completely agree with you about the discussion – it is awesome! Thanks to everyone!
This discussion is interesting, but it misses the point.
The trouble is that “Shall” “Must” and “Wollont on be”* are all actions, but they’re not the Actor’s Actions. This construction forces requirement into a passive voice – all wrong for good requirements. If you stick with “[Actor] [Action] [Object]” you’ll (likely) have something measurable, useful, and understandable. Drop “shall” entirely.
For a somewhat opaque view of the options, see http://tinyurl.com/chkxv3. What would a designer or tester focus on in the first three examples of the farmer, chicken and knife? Consider what you want your client to focus on, then choose the best sentence and requirement structure.
To reiterate: Do not choose between passive actions. Rephrase to the active voice (and the present tense). Translations will be simpler and understanding will be enhanced – whether you’re translating to Urdu or to PM-Speak.
___
*From Douglas Adams’ Hitchhiker’s Guide to the Galaxy (most versions)
@Julian – Thanks and welcome to Tyner Blain!
I completely agree with you that writing requirements in the active voice is better than the passive. There are times, however, when the system (under development) is the actor. “The oven must notify the user when the pre-set temperature is reached.”
I like the chicken-knife reference. Also reminds me of the old joke about ham-and-eggs breakfast: the chicken is involved, but the pig is committed.
Scott, you wrote, “The system shall respond in X seconds” as an example of an acceptance criterion, and contended that the shall vs. must issue is still relevant to such requirements.
If you write the acceptance criteria as preconditions, postconditions, and invariants (as I generally suggest), then it’s unlikely you would use shall, must, or should. Instead, you would write in the present tense with no modal verbs. I.e., you simply express the conditions that are assumed to exist at the beginning of the use case and the conditions that must (without actually using the word) exist (in present tense) upon completion of the use case.
But without getting into the weeds, let’s just back up a bit and consider the notion of a document full of sentences all starting with the same three words. What’s the point? Why not leave out those words and just explain up front that the sentences are things that are required of the system?
Or, if we insist on beginning the sentences with those three words, how hard is it to just explain what they mean?
@Roger – you make a good point for English-only interpretations. But how do you say that sometimes “should” means “must” and sometimes “should” means “ought to?” I believe that in English, the choice of using shall and must is arbitrary – but when translation is involved, it is not.
I am not inclined to believe that omitting the words, and relying on the readers to “fill in the blank” is a less ambiguous way to write, but I am open to the possibility, especially considering that more than one person has suggested it.
About six months ago a colleague devised a new priority categorisation for requirements that are sent externally as part of a tendered procurement exercise. The categories and definitions are:
Critical: Highlights a ‘bare essential’, without which the end-to-end solution/service will not be of value to the business. If the supplier doesn’t do this, they’re out.
Expected: These are important rather than critical. We expect these requirements to be met but non-conformance does not make a bid non-compliant. The supplier should do this and it’s included in the price.
Optional: Considered to be of lower relative importance or relates to a future aspiration. We want to know about this but it’s not in the price.
Using this categorisation really focuses the business customer to think about what is important to them. Until then we often used MoSCoW to categorise requirements but it doesn’t make the customer think enough about their requirements. Customer’s will respond “all my requirements are mandatory”!
So, the method of prioritising requirements also depends on the customer and the audience.
@Simon – thanks, and welcome to Tyner Blain!
I don’t think one single-axis prioritization scale provides any more clarity than another. The C/E/O scale is the same as MoSCoW, where C=M, E=S, and O=CW. I would expect that providing the same clarifying language in the MoSCoW framework would yield the same results. I’ve written MoSCoW docs for clients before, where that was their institutional policy, and the equivalent clarifications were included in the doc.
I do agree that managing expectations is critical, and that everything can’t be “top priority.” I remember in the dark ages, when working as a developer on a project, when the project manager introduced “Very High” as a new priority, to try and tease apart the massive bucket of “High” priority items.
@Scott: I recommend that each requirement identify the actor, action and object, regardless of who or what the nouns in the statement refer to. I have found this makes it really easy to describe a process from the solution perspective and the end-user perspective, regardless of whether a step is automated or manual. I also use the same unique ID for every requirement statement and the related box/bubble/shape and line on my diagrams. In many cases a project purpose is to replace one actor with another – which is really easy to describe in the documentation paradigm above.
@Simon: Where I work, we have tried a lot of prioritization techniques, and discovered that they only work if you prioritize on three distinct axis: benefits of change, implementation constraints and business constraints. Most methods (like MoSCoW) conflate these three, and ask the stakeholders to assign a single priority to encompass all of them at once. This can result in insane decisions. For example, oxygen and water are extremely expensive to send into space with astronaughts. If the perspective / bias of the stakeholder is implementation constraints, these will have a low priority. If the perpective is benefits, they are neccessary. If the perspective is business constraints, they are part of a negotiation about the number of astronaughts we can afford to send.
@Julian (re: @Scott) – Definitely great practices. We’re on the same page.
(re: your @Simon response) – Really good point about conflation of axes. Personally, I’ve had success going with a different approach:
1) Prioritize benefits as “pain and gain” – i.e. reducing negatives and adding positives, combining those to reflect a notion of utility – see my previous article on the Stakeholder Value Delivery Matrix, adapted from work by Roger Burlton.
2) Deal with business and implementation constraints as constraints – i.e. they bound the solution space.
3) When you can estimate costs, use those to drive a prioritization by bang for the buck – see my previous article on prioritizing sprints part 2. The discussion on that one (and part 1) provides good insights into the next level of detail (e.g. dealing with strategic initiatives and other orthogonal “priorities” that don’t map cleanly to a benefits matrix).
@Julian(18): I can’t see that “The sytem shall…” is passive, nor that “shall”, “should” etc. are some form of action. They are auxiliary verbs, to be used with a good old solid verb that indicates some real action. So the construct “The system shall print/show/do X …” PREVENTS a passive form. *wisenheimer-mode off* ;-)
I find it quite helpful to have a single sentence structure for granular, atomic functional requirements (or 2 -3 different ones for different situations, see below). Where’s the difference to acceptance criteria, where a common form is Situation-Event-Result. Actually I got accustomed to do some kind of requirements speed reading with such specs.
First fixation: First 1 or two words – the actor in this sentence (different from use case actor!). I can skip this fixation most of the simes, see below)
2nd fixation: 3rd word – says something about priority (this information can be put elsewhere, but I find it valueabe to read a spec’s”content” only, without distracting tags. makes sense if there are requirements with different auxiliary verbs, not just one)
3rd fixation: usually the strong verb (sometimes called process verb) – clearly indicating WHAT has to happen)
4th fixation: rest of the sentence – everything else I have to know to understand the requirement.
You can read a spec with better understanding at much higher speed (I dare to say at least 4 times faster) compared to a nice-sounding spec with varying sentence structures. Might be less boring, but hey, this is a spec and you will never win a Nobel Prize in literature for it! ;-)
WRITING lots of “the system shall”s IMOisn’t really an issue: we have word processors and other tools (like speech recognition) that help with tasks like that.
I use the following two sentence structures:
1) “The System [shall | should | can] [verb] [objects] ” with everything outside of the brackets being literal.
2) “The system [shall | should | can] provide [whom] the capability to [verb] [objects] …”
[Note from Scott Sehlhorst: I edited the above per Rolf’s request – the comment system had stripped out some content that was formatted with greater-than and less-than symbols. This stripping is in place to prevent malicious people from embedding javascript or other code into comments on the site. “em” “i” “strong” “b” “ul” “ol” “li” “blockquote” “cite” “a” and maybe some other html codes are all supported when well-formed – so feel free to use those (note that if you include multiple “a” (anchor) links in a post, the system will probably flag it for manual review before publishing. Sorry for the confusion! Tyner Blain actually uses the default “protection” of comments that is part of the standard WordPress installation, so we’re not doing anything fancy.]
where 1 indicates some action that is required to be performed by the system-under-spec. Example: “The system shall display date X”. No. 2 indicates, well, a capability, that has to be provided by the system-under-spec. Example: “The system shall provide the capability of editing date X”. NOTE that it does not help to write something like “the USER shall edit date X”, as this is requires something from the user, not the system. This might seem like hair-splitting, but I have seen lawyers quarrel over this difference.
my 0.02
@Rolf: Lots to think about. I agree with many of your statements – but not your conclusions. My disagreeable nature is largely the result of the organization I work for. Lemme ‘splain.
Where I work we have a very mature BA practice, with extensive organizational support. This includes 40+ in-house training courses, an accreditation program, enterprise-level BA standards / processes / tools, a formally sponsored community of practice, a formally sponsored BA Champion Group, all managed by a 3 person full-time Centre of Competency, etc. (I lead the Centre of Competency). We are also focussed on _solution_ rather than _system_ (as per BABOK 2.0), which means that many requirements describing process steps (for example) are executed by humans, not machines. A solution is comprised of people who execute processes using tools.
You said:
> I use the following two sentence structures:
> 1) “The System shall †with everything outside of the brackets being literal.
> 2) “The system shall provide the capability to …â€
In case 1, you said the benefit of “shall” is that it encourages the active voice and that it keeps a standard structure. We get these benefits through training and assessment. BAs learn to use the active voice and to use a single, simple structure for every requirement statement, and we have some organizational self-correction measures to maintain the standard.
Case 2 is trickier. We see this construction as destructive to effective communication and prioritization, and dangerous to the sustainability of our business. Our rationale: a capability is meaningless without understanding who will use it and the circumstances of that use. We have been burned by using this construction because it encourages the BA and stakeholders to break the association between what the solution must do and what the solution is supposed to achieve by doing it.
I’ll use a melodramatic example. Your government has a [date x] for you where [x=died]. In a requirement document, “The system shall provide the capability of editing DATE_OF_DEATH†is likely to be part of a long list of fields-that-can-be-edited, and unlikely to be associated with any particular process or task, though it might be associated with a screen.
In our company, we would have a Use Case called “Stop payment of death benefits to soldier’s family†with “Step 7. The USER edits DATE_OF_DEATH to match date supplied on FORM_2-973/W+a.†The narrative, preconditions, inputs, outcomes and postconditions are wrapped around the DATE_OF_DEATH field, and help define the impact it has on the stakeholders. We also try to trace the data-dictionary definition of DATE_OF_DEATH to each process, report and user that accesses it. (We usually get the process and report links, and find the users from there.)
That’s great, but the benefits roll in later, when somebody goes into the system to do a little maintenance on the DATE_OF_DEATH field. The cross-referenced solution documentation we produce helps the maintenance developer see the impacts of change – and means we are much less likely to make orphans starve.
Hey, I said it would be melodramatic. I don’t work in a life-and-death industry – but we know this kind of thing really happens.
As I said at the start – I agree with a lot of your post. We work really hard to make requirements boring-through-standard-structure, for instance. Thanks for the comments!
@Scott, item 28: I’ll take a look at the resources you reference. I didn’t find much last time I looked, so I had to get creative. I’d much rather reuse!
Drip irrigation systems have bubblers. You can buy them in Texas, as well as New England.
The ambiguities inherent in the requirements process are bad enough if you are dealing with only one natural language.
Uh, I just found out that Tyner Blain’s comment system has severely distorted the two expressions for sentence structures in post#29. Half of it or more is missing. I should have checked after submitting. As I was about to write about the topic on PlanetProject.wikidot.com, I’ll do so NOW and let you know when I’m finished. Please stand by and use the comment subscriptions.
@Julian: nice example. I can see what your context is, and why you chose to not use sentences like I do. I have worked for BA beginners most of the time, teaching BA practices. It seems all boils down to the salomonic answer: it depends! :-)
OK, here it is: http://tr.im/kwS8 A wiki article on How to write atomic functional requirements.
Feel free to do responsible changes.
Scott, thank you for writing about the issue, and hosting such a great discussion about it. Kudos! My respect goes to you and your work over the years, and I hope I cited you correctly.
@Rachel English: It depends on whether you are writing from a user perspective (use cases and the like) or a system perspective. See Scott(8). I’d say your style is perfectly well suited for the user perspective, although I’d avoid a “prior” and write what is prior before the other thing. Disambiguity requirements are much stricter if there’s a lot to loose, like money or lives. You might find the article instructive for your purposes, if you really need to write atomic functional requirements. Also see http://tr.im/kwN7 to find out whether a requirement is atomic.
@David Smith (15): There’s a place for the structure you mention, but only to complement various other structures. It’s hard to fit everything into ONE structure. See my wiki post mentioned at the top.
@Jeffrey Smith (16): I think we think along the same line of thinking :-)
On some projects, we experimented with using the MoSCoW words in the requirements to reinforce the stakeholder prioritisation. The problem with that is you end up with a requirement selected for an iteration that says something like:
“When the client has confirmed the order, the call-centre agent could be prompted with linked products to cross-sell”.
The developer (especially if a third-party supplier) effectively can ignore the requirement, as the term ‘could’ implies it was a choice and doesn’t matter if it’s not available.
We subsequently reverted to everything being a *must*, with the MoSCoW words (along with estimates of effort and value, and affinity to other requirements) helping drive selection for iterations.
Our experience with user stories also led to a more clearly stakeholder-centric first-person present-tense language:
“As a call-centre agent, when the client has confirmed the order, I am prompted with associated products to cross-sell”.
For projects where the first-person nature of this construct didn’t work, we can strip it down a little more:
“When the client has confirmed the order, call-centre agents are prompted with associated products to cross-sell”.
The affirmative nature of the present tense “are” means that we don’t have to say ‘must be able to’. By the same token, when we say “call centre agents cannot override the discount rate for new clients” — we don’t have to say ‘must not be able to’.
Clearly, when the event triggering an activity is not caused by a person, then we typically resort to anthropomorphising the system:
“The document management system alerts owners of all documents left checked out for 24 hours or more”.
While we can shift the focus back onto the stakeholder involved, by redrafting to:
“As a document owner I am alerted when any of my documents are left checked out for 24 hours or more”
— or in the third-person:
“Document owners are alerted when any of their documents are left checked out for 24 hours or more”.
— this doesn’t specify what is doing the alerting. So making it stakeholder-centric is not always the clearest form.
David Morris, your “could vs. shall” problem is one of carrier and carried. In this case, the carried is a policy, which might change over time, as such, it is a good candidate for being treated as a business rule. The programmer would have to supply some variable that the policy would drive. The action taken by the program would depend on the value of the variable. So the solution would be more like, the programmer must implement funcitonality to support the ability to do or not do a cross sell.
In general relativity, there is the force of attraction (gravity) and repulsion (weak force?). The net effect of these two forces is to establish a field over the system life where at some point the forces are balanced. In between is a borderland, rather than a binary border. In deterining the age of life on Earth, this borderland situation leads various estimates. Whenever you see a distinct binary, try to think in terms of a pair of forces.
Beyond the border issue is the notion of software as a media. A radio signal is a mix of a carrier wave and a (program content) carried wave. Software as a media is code carrying, in an enterprise, business policy. Sadly, the term business rule was hijacked a long time before the distinction between database rules and business rules got clearer. The carrier vs carried paradigm should help.
It is said that programmers abstract away from requirements. This statement is true in that programmers have to think of many things distant from the tasks or activities being enabled at the interface. Again, carrier vs. carried.
In my last job we only had two priorities for requirements, Mandatory and Non-mandatory. Along with the “M” or “N” I wrote each requirement in the imperative, e.g. “M – Allow user to select one department from a dropdown list”, or “N – Highlight records with negative balance”. This always worked fine for me, though I had the luxury of sitting right next to the developers!
Translating into MoSCoW terminology, mandatory was “Mo” and non-mandatory was “SoW”, and C was left out of the mix. To my mind, C doesn’t seem like a requirement, just a design consideration, and belongs in a later iteration cycle, during design.
The IEEE link is broken for me.
Interesting discussion and I sort of agree with everyone to some extent.
I was raised with a Mil-Std requirements background. We has specific rules:
– shall is compulsory and failure to deliver will kill the project.
– should is a requirement, but we can find a workaround if it is not delivered on first release.
– could is a nice to have we’d like it if there is time and money to spare (yeah, like that ever happens).
– will is a statement of fact with zero cost to deliver (i.e. it already does this).
Since moving into business and a use case centric approach, I now prefer the precondition/postcondition active voice method of writing requirements (i.e. my requirements state what the system does, not what it must do). This had the advantage of removing unnecessary words from the requirement, and priority is tracked with e requirements management tool (as it should be). It is also a nicer way to present your requirements to the tester (IMO).
All functional requirement statements can be written in the form:
‘Upon’ ‘the system’ , within .
For example:
Upon receiving a request to display the menu, the system [shall display | displays] the system menu to the customer within 2 seconds.
Interface is needed when the system interacts with more than one actor, in order to clarify who gets the results (there may be two or more outputs to several actors).
Time limit is required in order to test the requirement.
Interesting article.
I also find that confusion abounds between Must/Should/etc as ways of stating requirements and Must/Should/etc as a priority system using MoSCoW.
A very interesting subject … and one which I have to deal with at present.
So what if one can get 21/41 for “shall” in the translation matrix?? This may be more idictative of the way in which languages are constructed than with an inherent confusion in the use of the word “shall” in English alone.
The perceived problem with “shall” is related to the associated word “should”. If you google translate the word “should” you get the same result of “devrait” in French as for “shall”. What seems to be happening here is that the translator is selecting the conditional in conjugation. This would be correct as, “shall” does imply a predition of futurity. That is … something SHALL occur IF some other condition prevails. I would grant that this could be used as an illustration of confusion and thus a reason to use “must”. However, I think that all this ignores the importance of context. The words “shall” and “should” have particular meanings with respect to contracting. I don’t believe that there is a confusion within this context which necessitates the use of the word “must”.
… You shall do something and if you don’t then the contract is not fulfilled.
… You should do something, but if you don’t than the contract would still be fulfilled.
This doesn’t show up in translation since only the word is translated, not the context. To simply say that something should be done represents the idea that it would be done. The word “must” gets 41/41 in the matrix because it is emphatic that something must be done regardless of conditions.
I suppose in a way, my main objection to the use of the word “must” is that it is too bossy.
… You shall do something and I expect you to do it.
… You must do something and you bloody well better do it and just to make certain I am going to stand here and watch you do it.
eduard alf
Eduard – thanks for the thoughtful comment, and welcome to Tyner Blain! I love the “…and watch you do it.” bit at the end.
I agree that “must” can sound bossy. I believe you acknowledged that it is unambiguous. Very few people that I’ve met can parse (language / documents / context) as effectively as you demonstrate in your examples.
Anecdotally, I’ve had people fail to parse “shall” and I’ve yet to have someone complain about “must” be too harsh. When documents are potentially going to be consumed by people for whom English is a second language, I’m going to stick to the unambiguous, because it keeps working for me. I do agree with your point, I just see it as the lesser of two evils (when compared to “ambiguity risk”).
Thanks again,
Scott (@sehlhorst on Twitter)
This whole thing is a tempest in a teapot. So what if translations of “shall” turn into other terms?? Perhaps the solution is to improve the translation. The difference between “should” and “shall” is obvious and it is the fault of a lazy translationer if there is a mixup in say French to use “doit” or “devrait”.
The problem with “must” is that it is very aggressive. That’s Ok as far as talking about “the system must” although it is preferable to state “the system is or does”. Systems are of a nature that they have to do the thing for which they are designed. One would not normally say “the airplane should fly”. Although it can be said as to mouth the words or write them down, the possibility of its use in a specificatin is remote.
Seriously. Is it really going to be the case that someone will deliver an airplane that doesn’t fly and then the manufacturer to respond … “Gee, you didn’t actually tell me that it had to fly!!”
Where “must” runs into a problem is when applied to people and their actions. An instruction might say “you shall cross the street”. It implies that if you are there, then you are to do the crossing. On the other hand the phrase “you must cross the street” not only means that you are required to cross the street regardless of where you are or what you might feel, but it also implies …. “you will bloody well cross the street and I am going to stand here the while with a whip in hand and make sure you do it”.
Being a Canadian and of the older generation, I find that this move to “must” is representive of how today’s society is becoming very authoritative, aggresive and hard. And we seem to be doing this because; (a) there are too many lawyers, and (b) people don’t know how to do a proper translation.
Fun photo showing how translation of expression of requirements can go horribly wrong!
http://sehlhorst.smugmug.com/Other/blog/shenzhen-sign/1180618030_BMHFf-S.jpg
I know this much, when writing a technical manual from MIL-STD-38784 DoD Standard Practice for Manuals, Technical: General Style and Format Requirements: there is no ambiguity. It states; . . . .
4.3.8 Use of “shallâ€, “willâ€, “should†and “mayâ€.
Use “shall†whenever a manual expresses a provision that is binding. Use “should’ and “may†whenever it is necessary to express non-mandatory previsions. “WW maybe used to express a declaration of purpose. It maybe necessary to use “will†in cases where simple futurity is required, e.g. “Power for the meter will be supplied by the ship.
Just a very quick remark: do you see how ambiguous this section of the MIL standard is?
Hah. When will power be supplied, exactly?
Thanks, Arnold for the great reference!
My opinion – that is an unfortunate choice of terms to be used when writing specifications. You may be “required” to use it, but that doesn’t make it good.
It strikes me as funny that you do not consider the negative form “must not” even though it is in the title of your article. I bet you would get noticeably worse results in you roundtrip experiment.
In fact, the literal German translation “must not” –> “muss nicht” is a permissive rather than prohibitive phrase. Translating back by meaning (i.e. not literally) you get “need not”. In that sense, “shall” / “shall not” fare better in the translation to and from German.
My conclusion is that the choice of words is not as important as defining the words that you use (that must be used) in your requirements as “term” with a set meaning. That definition must of course be shared with the readers of the requirements.
Really great points, Malte, thank you very much!
I learned to always use the positive form vs. the negative form when structuring the grammar of requirements; “Must prevent” is better than “Must not allow.” Frankly, I’ve never challenged that teaching, I’ve just taken it on faith that the positive approach is better.
Permissive vs. prohibitive is a fantastic way to frame the stylistic choice of how to avoid ambiguity.
I completely agree with the precept that agreeing on word choice (and interpretation) with your readers is the only thing truly required. At the time I wrote the article, I was trying to address a challenge of not having the ability to reach that understanding up-front, and hoping to minimize the damage of misinterpretation.