12 When to Watch your Words Carefully
In requirements engineering, there are a number of cases in which you must watch your words carefully. Some of them are listed below.
12.1. Contracts
Disclaimer: We’re not lawyers. Nothing in this (or any other) section is legal advice. Rather, this is all academic teaching and business advice. For actual legal advice, consult your company’s lawyer.
Very often, a fixed price contract will “include the requirements specifications by reference”. What that means is that although it doesn’t seem like you’re writing a contract while you’re writing the software (and possibly hardware) requirements specifications, that (or those) specification document(s) may be included as a part of the contract, simply by the contract stating that the document is included by reference. Thus, you must keep in mind contractual rules while writing the document(s).
One of the most pertinent rules in writing contracts is that the person (or party) who did not write the contract is entitled to any reasonable interpretation of each clause of the contract. There are two take-aways from this: (a) Don’t have any ambiguities in anything you write, and (b) watch out for the phrase “this Agreement is the work-product of both parties” or anything like that in a contract, because when you see that, the person who wrote the contract is lying with the intent of having you pay for their mistakes.
12.2. Ambiguity
The biggest way to trouble in a contract or in a project is to have ambiguities in the contract or in the specifications. The best way to avoid ambiguities is to examine every sentence in the documents, and ask yourself “Is there any way that I can think of to misinterpret this, either through stupidity or malevolence?” Both of those can and will be used against you. If you have to explain something in depth, do so. If you have to draw a picture, do so. If you have to use a different word, do so.
If you’re working with any speakers of a foreign language, and their language inflects entire sentences to the positive or negative, don’t have any double negatives anywhere in your document, because double-negatives are not translatable into most languages.
Another negative effect of ambiguity is that you’ll inadvertently pit the development team against the QA team, costing both teams a lot of wasted time. If you’re ever in a situation where the developers think that a certain requirement means one thing, but the QA people think that the requirement calls for something else, then it’s not the fault of the development team, and it’s not the fault of the QA team. It’s then the fault of the requirements team. The remedy is not to declare one team right and one team wrong — the fix is to fix the requirements. A corollary: If a developer (or anyone else) asks you what something means or how to interpret it, don’t just answer the question — answer the question and fix the requirements so that nobody will ever have to ask again.
Some managers, customers, or suppliers may use ambiguous phrasing to gain “wiggle room”. Wiggle room is exactly the opposite of what we’re trying to do in requirements engineering, so correct any such word usage.
12.3. The Deadly Word “All”
Use of the word “all” in a requirements document can be extremely costly. An oft-seen mistake is something like this: “The web-site shall support all browsers.” That seems an innocuous enough phrase, but it can cost a fortune, in two ways. First, testing can go on for hours, when QA brings in 600 browsers to test with and has at it. Second, your customer may find that 601st browser that the product doesn’t work with, and hold you over the coals for some monetary concession, or worse, they may be using that 601st browser for their actual production environment. “All” doesn’t just hold to browsers. It’s too easy to say “all operating systems”, “all languages”, “all applications”, and so on.
When the word “all” or “most” or any unquantified word appears, remove it, and replace it with something else. Typically, you’d use “including but not limited to”, followed by a list, usually with version numbers. For instance, “shall work with all browsers” could be replaced with “shall work with browsers including but not limited to Chrome version 90.0.4430.93 (x86_64), Safari version 13.0.2,” and so on.
12.4. The Words List
Requirements specifications should be written entirely in terms of what the facts are now, what the facts will be, what is desired, what the system must do, and what the users are likely to do, often with the added means to deal with what might happen. Specifications should be written in the third person only, meaning that “I”, “we”, “my”, “mine”, “you”, “your”, and “yours” should not appear. Exception: Use Stories are generally written in first person.
With that limitation, you’ve got everything you need to know about phrasing for the less formal specification styles, such as Use Case. But, when writing in the very formal specification styles, such as IEEE 830 or MilSpec, and especially in contracts, certain words are preferred and have special meanings:
Can: “Can” means that something is possible, and not that we’re giving permission. For instance, a disk drive can fail at any time.
Could: “Could” means that something is possible, but usually conditional on something else.
Did (including implied “did” using an “ed” at the end of a verb), Does (including implied “does” using an “s” at the end of a verb), Is, and Will: These words are all direct statements of fact. Use these words only when the fact holds with or without the action of your team.
May: In many circumstances, “may” is unclear. It can mean that something can happen, that we have given permission for something to happen, or that something may happen. In any circumstance where “may” is equivalent to “can”, use “can”. In any circumstance where “may” means “might”, use “might”. You may use it where permission is given, but it’s better to state that something is permitted or allowed.
Might: “Might” is the word to use when an event has some likelihood of occurrence.
Must and Shall: These are the words to use when something is a requirement. You generally want to lay a “must” or a “shall” on the system. You must not attempt to lay a “must” or a “shall” on a user, because you can’t control the users, nor are the users listening to your guidance 100% of the time. The use of “shall” is traditional in requirements, but the more modern “must” is certainly acceptable. Exception: It’s ok to state that the user must do one step in order to proceed to some other step, but since that’s really a requirement on the system, even this exception would best be rewritten as a requirement on the system. Note: In the UK, “shall”, when used with the first or second person, means “almost certainly will”, but since we’re not writing specifications in the first or second person, that doesn’t matter.
Should: “Should” is the much weaker relative of “shall”. It is advisory only, and has no bearing on requirements at all. Think of it as meaning “it would be nice if”. If this word appears in a requirements document at all, it should only appear when no other word will do. QA personnel should ignore any sentence with “should in it.
Would: “Would” is the conditional form of “will”. It should be used rarely, if at all, and even then, mainly to describe possible external stimuli.
12.5. How Things Can Go Wrong
Use of the wrong words can mean that you’re obligated to things you hadn’t planned on, or that your subcontractors are not obligated to something you needed from them. The “deadly words” can cost a lot in QA time even when no contract is involved.
12.6. Discussion Questions
- What are good ways to replace “all” or “any” in specifications?
- When should “all” and “any” be used, and when not?
- Where you live what are the differences, if any, between “must” and “shall”?
