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?
Option 1: use RFC 2119
According to RFC 2119:
- MUST This word, or the terms "REQUIRED" or "SHALL", mean that the definition is an absolute requirement of the specification.
This is also the most current use of the word "shall" from what I've seen in the requirements.
Option 2: use present tense
If the requirements are mostly mandatory, you may also want to formulate the requirements in present tense, without "must", "shall" or other keywords. Example:
The undo history is preserved when the application is closed.
The requirement clearly states, by its present tense, that the requirement is mandatory. The history should be preserved, and if it's not, the software fails to pass this requirement.
Such way of writing the requirements allows them to be slightly more readable, without losing their mandatory property.
Option 3: use your own conventions
Note that you may define your own terminology in the documents you write. That's why most documentation starts by defining the terms, including "must", "can", etc. For example, HTTP specification contains such section: 1.2 Requirements.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [34].
An implementation is not compliant if it fails to satisfy one or more of the MUST or REQUIRED level requirements for the protocols it implements. An implementation that satisfies all the MUST or REQUIRED level and all the SHOULD level requirements for its protocols is said to be "unconditionally compliant"; one that satisfies all the MUST level requirements but not all the SHOULD level requirements for its protocols is said to be "conditionally compliant."
Using a convention which differs a lot from the generally accepted practice is still a bad idea, and must be done only if you have serious reasons to do it.
Shall is still used in software documentation. It was a subject of discussion in my software engineering course and it's also present in field documentation.
An example can be found in the Joint Strike Fighter's C++ coding standard. In section 4.2 under Rules on page 11. It specifically defines the following:
4.2.1 Should, Will, and Shall Rules
There are three types of rules: should, will, and shall rules. Each rule contains either a “should”, “will” or a “shall” in bold letters indicating its type.
Should rules are advisory rules. They strongly suggest the recommended way of doing things.
Will rules are intended to be mandatory requirements. It is expected that they will be followed, but they do not require verification. They are limited to non-safety-critical requirements that cannot be easily verified (e.g., naming conventions).
Shall rules are mandatory requirements. They must be followed and they require verification (either automatic or manual).
So at the very least, within the last decade for government contract work, shall does have a great deal of force. I suspect it's still much the same in the private sector, though perhaps not nearly as strict in the case of projects not involving multi-billion dollar avionics.
RFC 2119 defines the meanings of various words used in specifications (such as other RFCs). It defines SHALL as a synonym of MUST. I think it's preferable to use MUST, as it conveys the meaning more clearly.
Background: I speak from the viewpoint of roughly thirty years experience, almost all of it in the defense industry (except for two years in telecom, at Nortel Networks).
Definition: A requirement is something that you are required to verify. You may verify by analysis, by demonstration, by test, by mathematical proof, or some other approved way, but you absolutely must verify that your product meets that requirement. If your product doesn't meet that requirement, or if you have not PROVEN that your product meets the requirement, you aren't done.
In the defense industry, at least, a statement in a requirements specification is considered to be a requirement if and only if it uses the word "shall". There are no exceptions whatsoever to this rule. If it said "shall", it was a requirement, if it didn't, it wasn't. Period. End of sentence, end of paragraph, end of chapter, end of book.
This makes it VERY easy to decide whether a particular statement in a requirements specification is or is not something that must be tested, or otherwise verified.
RFC2119 formalized terms of art long used for writing RFCs. At the time the original RFCs were written, long before RFC2119 was penned, the original RFC writers, who were very familiar with defense industry specification conventions, were trying very hard to avoid appearing as though they were writing requirements specifications for the net as a whole. The very name, "Request For Comments", was chosen for that specific reason, to avoid dictating to the other researchers. (Herding cats is a lot easier than herding researchers.) Hence they carefully avoided using the word "shall", and used "must" instead. The idea was the same: if you wanted to write e.g. a Telnet client, and claim it conformed to the Telnet RFCs, you were required to comply with the "must" statements.
During my short stint in telecom, I did have to read RFCs, and I did have to read and write non-RFC requirements specifications. The RFCs all used "must" to denote requirements. The requirements specifications all used "shall" for that purpose.
If I were in your shoes, and writing non-RFC requirements specifications, I'd use "shall", and only "shall", to denote requirements and only requirements, for the reasons described above. Similarly, if you're writing RFCs, use the RFC 2119 language, and incorporate RFC 2119 in your RFC as the other guy described.
Several good answers here, the short answer is "yes", you should use "shall" in technical requirements documentation. As a Technical Requirements Analyst and Product Owner, I can add one piece that I do not see in some of these very good answers.
In Agile software development methodology, we often replace legalistic sounding language with language which is more conversational. This does not mean in any way that the requirements are less exact or stringent, just that they are often phrased somewhat differently.
For example: "The address modal shall appear when the user activates the order button" might be replaced with a user story which sounds more like this: "As a user, I need a way be sure the order is shipped to the correct address so that I can ensure my shipment gets to me." The format for this is; As an X, I need Y, so that Z. This actually ensures that a lot of contextual information is included in the work item the developers pick up which is not normally included in classic use-case type requirements language.
We use what we call "user stories", "epics", and "themes" to elaborate requirements in agile development. They read more like a story (hence the name), so usually you don't use words like "shall" (although I have actually used "shall" in agile product requirements), but you absolutely must make sure that these user stories, epics, etc, are just as specific, testable, and verifiable as any classic use case. Even though you may not use "shall" very often in agile software requirements, things should be spelled out in such a way that they are absolutely explicit and "shall" might as well have been used.
If you are not writing requirements for an agile development process, then see the excellent answers above: requirements shall be verifiable, testable, and precisely defined, or software development projects go off track very quickly.
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.
The "shall" language is universally accepted, as testified by the official recommendation from ISO (International Organization for Standardization):
“shall” indicates a requirement “should” indicates a recommendation “may” is used to indicate that something is permitted “can” is used to indicate that something is possible, for example, that an organization or individual is able to do something
SOURCE: http://www.iso.org/iso/foreword
ISO standards are produced across international and disciplinary/business areas, so I would say that this language is definitely a good starting point - with the best practice being to explicitly say which terms you'll use and what they mean!
You certainly could use "shall" in this fashion, and it would not be a bad thing, but don't expect your programmers to know the difference. I never saw this usage during fifteen years of writing code from formal specs, so probably a lot of other coders haven't either. If you have a use for the distinction, go ahead, but be careful to explain what you're doing.
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.
