Should one use the legal "shall" in requirements documents and specification documents?
At least in the US, "will" has replaced "shall" in most every context, with the notable exception of the "legal shall". Shall is used instead of will in legal documents to indicate a sense of obligation or requirement; e.g. "the defendant shall vacate the premises by October 16".
In software, requirements documents and specification documents serve close to the same purpose as the aforementioned legal documents; does this mean shall should be used in a similar fashion as a result?
This post was sourced from https://writers.stackexchange.com/q/6450. It is licensed under CC BY-SA 3.0.
2 answers
With requirements, shall / shall not. Nothing else. "Shall" is a very specific; it's a keyword I can search for. Must, must not, will, will not: That's for the explanatory text. (And no shalls in the explanatory text. That defeats making "shall" a search term.)
How not to do it: I helped write a proposal long ago where the RFP had shall requirements, should requirements, shall options, and should options. What a mess! A viable proposal had to meet all of the shall requirements and the shall options, and had to address all of the should requirements ("we can't do this" was one way to address those things). Should options were optional. The base offered price had to cover all of the requirements (shall and should); options had to be priced separately and individually. We didn't win; nobody did. Someone high up eventually put a stop to that convoluted RFP.
With tests, shall and should don't belong. The test criteria says how to interpret the results of the test: Did the test pass or did it fail? The criteria might be plain English, a boolean, math, but not shall. There's no reason to say shall. That the test must eventually pass is implied.
This post was sourced from https://writers.stackexchange.com/a/6455. It is licensed under CC BY-SA 3.0.
0 comment threads
Although the ISO may favor keeping "shall," I agree with PlainLanguage for this one: https://plainlanguage.gov/guidelines/conversational/shall-and-must/
Use “must” not “shall” to impose requirements. “Shall” is ambiguous, and rarely occurs in everyday conversation. The legal community is moving to a strong preference for “must” as the clearest way to express a requirement or obligation.
I favor must for requirements, should for a recommendation, could for an option, and will for statements of fact.
We must set our clocks forward for Daylight Savings. You should plan your sleep schedule to account for this. You could move to a state that stays with one time-scheme all year. Regardless, the earth will orbit the sun just as it always has.
0 comment threads
0 comment threads