: 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

Vote Up Vote Down

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.

(0)

Vote Up Vote Down

Although the ISO may favor keeping "shall," I agree with PlainLanguage for this one: 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)

Vote Up Vote Down

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: 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!

(0)

Vote Up Vote Down

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.

(0)

Vote Up Vote Down

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.

(0)

Vote Up Vote Down

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.

(0)

Vote Up Vote Down

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.

(0)