{"id":3430,"date":"2013-08-07T08:30:56","date_gmt":"2013-08-07T15:30:56","guid":{"rendered":"https:\/\/www.jamasoftware.com\/?p=3430"},"modified":"2023-01-12T16:56:46","modified_gmt":"2023-01-13T00:56:46","slug":"elements-of-requirements-style-part-2","status":"publish","type":"post","link":"https:\/\/www.jamasoftware.com\/legacy\/blog\/2013\/08\/07\/elements-of-requirements-style-part-2\/","title":{"rendered":"Elements of Requirements Style, Part 2"},"content":{"rendered":"
Parent and Child Requirements<\/h2>\n
When writing requirements in a hierarchical fashion, the BA records a parent requirement and one or more child requirements. The parent requirement is satisfied by implementing all of its children. Here\u2019s an illustration of a hierarchical requirement with some problems: 3.4 The requester shall enter a charge number for each chemical ordered. 3.4.1 The system shall validate charge numbers against the master corporate charge number list. If the charge number is invalid, the system shall notify the requester and shall not accept the order. 3.4.2 The charge number entered shall apply to an entire order, not to individual line items in the order. Notice that this parent requirement, 3.4, is written in the form of a functional requirement. It\u2019s not entirely clear how many requirements are represented here: two or three? Also notice that there is a conflict between the parent requirement and one of its child requirements, 3.4.2. If each ordered chemical is a line item, exactly how many charge numbers is the requester supposed to enter? These sorts of problems disappear if the parent requirement is written in the form of a heading or title instead of in the form of a functional requirement. Consider using this style whenever you have a set of child requirements that, in the aggregate, constitute a parent requirement. Following is an improved version of the preceding example: 3.4 Charge Numbers 3.4.1 The requester shall enter a charge number for each chemical in an order. 3.4.2 The system shall validate charge numbers against the master corporate charge number list. If the charge number is not found on this list, the system shall notify the requester and shall not accept the order.<\/p>\n
What Was That Again?<\/h2>\n
Ambiguity is the great bugaboo of software requirements. Ambiguity shows up in two forms. One form I can catch myself. I read a requirement and realize that I can interpret it in more than one way. I don\u2019t know which interpretation is correct, but at least I caught the ambiguity. The other type of ambiguity is much harder to spot. Suppose the BA gives the requirements specification to several reviewers. The reviewers encounter an ambiguous requirement that makes sense to each of them but means something different to each of them. The reviewers all report back, \u201cThese requirements are fine.\u201d They didn\u2019t find the ambiguity because each reviewer knows only his own interpretation of that requirement. Let\u2019s see some sources of ambiguity to watch for and some suggestions about how to write less ambiguous requirements.<\/p>\n
Complex Logic<\/h2>\n
Complex Boolean logic offers many opportunities for ambiguities and missing requirements. Consider the following paragraph: If an order is placed for a chemical to a vendor, the system shall check to see if there are any other pending orders for that chemical. If there are, the system shall display the vendor name, vendor catalog number, and the name of the person who placed each previous order. If the user wishes to contact any person who placed a previous order, the system shall allow the user to send that person an e-mail message. This long requirement is difficult to read and contains multiple functionality descriptions that should be split into separate requirements. Plus, it has some gaps. Writing requirements in this style makes it difficult to see whether the outcomes of all the if\/then branches are specified. \u201cElse\u201d conditions are often overlooked with this sort of textual representation. Nested \u201cor\u201d, \u201cand\u201d, and \u201cnot\u201d clauses are better represented using a decision table or decision tree. A decision tree such as that shown in Figure 1 would immediately reveal that the system\u2019s behavior is not specified if there are no pending orders for that particular chemical. Other false outcomes from the decisions are also unspecified. Implicitly, perhaps the reader will conclude that the system should do nothing if the various \u201cif\u201d conditions described here are false, but that\u2019s an assumption forced by the incompleteness.<\/p>\n
Figure 1. Sample decision tree for complex logic.<\/p><\/div>\n
Expressions involving compound operators\u2014such as \u201cIF this AND (that OR the other)\u201d\u2014are even more confusing:<\/span> If the amount of the cash refund is less than $50 or the amount of the cash refund is $50 or greater and the current user is a supervisor, then the system shall open the cash register drawer. Making this requirement understandable and unambiguous requires either parentheses (awkward) or splitting into multiple requirements (better).<\/p>\n
Negative Requirements<\/h2>\n
Negative (or inverse) requirements are another source of confusion. Try to recast inverse requirements in a positive sense, to state what the system will<\/i> do under certain circumstances. Table 1 states several functional requirements, all drawn from actual projects, that contain negation, along with possible ways to rewrite them in a positive sense. I\u2019ve also restated these passive-voice requirements into the less ambiguous active voice, which clearly shows what entity is taking each action. Note that changing a negative requirement into a positive one often requires inserting the word only<\/i> to identify the conditions that permit the system action being described to take place. In the third example, note also the ambiguity between cannot<\/i> (as in \u201cnot able to\u201d) and may not<\/i> (as in \u201cnot permitted to\u201d). Table 1. Removing Negation from Functional Requirements<\/p>\n
\n\n
\n
Before<\/td>\n
After<\/td>\n<\/tr>\n
\n
All users with three or more accounts should not be migrated.<\/td>\n
The system shall migrate only users having fewer than three accounts.<\/td>\n<\/tr>\n
\n
The registration process will default to International English and will not present a localized experience until country and language are selected.<\/td>\n
The registration process shall default to International English. After the user selects the country and language, the registration process shall present a localized experience.<\/td>\n<\/tr>\n
\n
A domain name cannot be transferred to another registrar during the registration grace period.<\/td>\n
The domain administrator may transfer a domain name to another registrar only after the registration grace period.<\/td>\n<\/tr>\n
\n
The PC administrator will not have the ability to change the FZL-Web user.<\/td>\n
Only the system administrator shall be able to change the FZL-Web user.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
Avoid double and triple negatives in all circumstances. Consider this example: Training rewards and points will not be visible to users who cannot participate in training rewards. We can rephrase this double negative into a positive statement that\u2019s easier to understand: The system shall display training rewards and points only to users who are permitted to participate in training rewards. Following is another illustration of recasting a double negative into a positive using an \u201conly\u201d constraint. The original requirement said: Users who are delivered service without being authenticated should not generate accounting records. Let\u2019s state it as a positive action that the developer can actually implement: The system shall generate accounting records only for users who are delivered service after being authenticated. Multiple negations can lead to ambiguous requirements, as illustrated here: Records, however, should not fail validation if these attributes are not present at all. Does this mean that the records should fail validation if the attributes are present? Probably not. The context might make the meaning of this requirement clearer, but as it\u2019s written, it raises a question in my mind. The main message here is to think positive when writing requirements! <\/p>\n
![\"\"](\"https:\/\/static.jamasoftware.com\/www\/imports\/2013\/08\/a9f1.jpg\")