Welcome to module two. As we saw in the last module, the writing of good requirements is essentially about removing the ambiguity from the resulting statement. We first identified a suitable structure for the statement, and then we began to look at the rules that we should keep in mind when writing requirements. In this module, we continue to move through the rules. Particularly as they relate to vague and superfluous words. In these presentations, we'll consider the writing of text-based requirement statements. As we saw in the last presentation, we need to consider what must be done when writing those requirement statements, so that we can avoid ambiguity. We saw that there are a number of rules that we need to follow to develop useful requirements. In this presentation, we'll address the first of those rules. Our first consideration is that the subject of a requirement statement should be appropriate to the level at which it's stated. So what that means is that system level requirements should begin with the system shall. Subsystem level requirements with the subsystem shall, component level requirements with the component shall and so on. When writing requirements in any given level, we must then consider the current level is appropriate to state that requirement at that level, or perhaps it's better to start the requirement at some lower level or perhaps it should have been started at some higher level. And, of course, we have to verify the requirement at the level which it's stated. So what that means is, that if we have something detailed, like something [iii] component, for example, it's probably inappropriate to be making a statement about it at the system level. And whereas, is a good reason to do so, for example, we might want to mandate that requirement. It also means that the higher level requirements are mostly logical not physical. That is, they don't state a solution because it's not normally appropriate to state solutions at those higher levels. Now, first consideration regarding ambiguity is to make sure that the items in the list are explicit. Often, when a list of conditions is given, it might not be clear whether all the conditions must hold. That is, there's a conjunction of some sort, or any one of them might hold, that is a disjunction. The wording of the requirement should make this clear. So for example, if we have the requirement here, The Audit_System shall allow the Clerk to change the Status of the Item when, and then there are three things listed. It's not clear that statement with the action can be alert when any one of the conditions holds or when all the conditions hold. So when all conditions would hold, we should write, The Audit_System shall allow the Clerk to change the Status of the Item when the following conditions are simultaneously true and that we would follow what the list of conditions. If what we meant was when any one of the conditions hold, we should write, The Audit_System shall allow the Clerk to change the Status of the item when any one of the following conditions is true, followed by the list. Another source of ambiguity relates to the position of the subject and the object in the sentence. The relationship between the subject and object is related to what we call the voice of a verb. In a sentence written in the active voice, the actor that performs the action of the verb is the subject of the sentence. In the passive tense, the subject is the target of the action. So for example, the System shall display the Account_Balance. Using the active voice, it's subject, verb, object. The statement the Account_Balance shall be displayed by the System is in the passive voice, object, verb, subject. Now, the requirement statement must make obvious what or who is performing the function. That's also important because the subject of the requirement is going to be the subject of the verification statement. We like the active voice because in that voice the subject is always identified first. In the passive voice, the true subject of the requirement is not always obvious. In this case, for example, it's not the responsibility of the account balance to display itself, it's the responsibility of the system to perform that action. It's a system that will be tested not the account balance. The difficulty with the use of the passive voice arises because the wealthy will fit to ask for inaction without specifying the subject at all. For example, I could simply state, The Account_Balance shall be displayed. Now, the discipline of writing the statement in the active voice avoids this ambiguity because the author has to write the subject shall display the account balance. And they really shouldn't be able to continue until they can determine who or what that subject something should be. When being careful to write good requirements, use of the definite article, the, is preferable to the indefinite article a. The problem is that the use of the indefinite article is tantamount to using any one of, and that's not verifiable. So for example, a baby is a user, a user of baby food. But the system would file if the test agency sought to verify that a baby could order, receive, open or serve, or any other act, like independently consuming baby food. On the other hand, if the requirement refers to the the user, the reference is explicit to the nature of the user defined in the glossary, presumably an adult. For example, the requirement. The System shall allow a student to Enrol on the first encounter, at the first attempt, is easily failed if the test agency can find any single person who is unable to Enrol. Perhaps we could recruit one of the babies we used as the test subject in the previous example. So we need to write the requirement to be explicit. We should say, The system shall allow the Student to Enrol on the first encounter, at the first attempt. And of course by defining student in the glossary, we are being even more explicit. If we use a separate term in the document, the reader is entitled to infer that we have meant the change in meaning, or, we're referring to a different entity. So we should always use the same term to mean the same thing, or to refer to the same entity. For example, in a subsystem specification, the following three requirement statements, the radio shall, the receiver shall, the terminal shall, probably all refer to the same subject. And the statements must be modified to use the same word, if that's the case. Or, if they're meant to be different, the words must be defined to be so. Notice that if the subject is different in the same specification, there's probably a mistake because the subject should always be the subject of that specification. Ambiguity in a requirements type is also caused by the use of vague words of which there are very large number. We just listed some here. So you've got words like all, or any, or many, or some, or several, a lot, a few, approximate, nearly, expandable, effective, generic, optimal, small, large, high-speed, medium-sized, best practice, user-friendly, and so on. This is really only a list of the common mistakes, of course. There are many other words equally as vague. So here are some requirements that need to be fixed. The User_Interface should be flexible. The User_Interface should be user-friendly. The User_Interface should require minimal training. There's a common statement made when writing specification employed. Look at some common mistakes we'll see how to fix them. One of the most common uses of vague words is all, or any, or both, when they're used to refer to a set of things. The use of these words has two problems. First, it's not clear when we say all, for example, whether we're referring to each one of the elements of the set or the entire set simultaneously. Second, the set is often not defined and the requirements refer to something such as all users, which is unverifiable since we would need to confirm that each set of users could perform the function. So instead of obeying words such as all, or any, or both, the best practice is to use each instead. So for example, The Record_Subsystem shall store the location of all Line-Items, or The Record_Subsystem shall store the location of any Line-Items are both invalid requirements, because of the all or the any, and both are unacceptable. We need to rewrite each. By for example saying, The Record_Subsystem shall store the location of each Line-Item. And then what a Line-Item is, of course, is defined in a glossary. A second common issue related to the use of words that are vague because they can't be measured. Words such as prompt, fast, routine, maximum, minimum, optimal, nominal, easy to use, high speed, medium-sized and so on. Those vague terms must be replaced by a specific quantity that can be measured, so that we can verify the requirement. So, for example, if we say, The Radio shall use minimum power, we can't measure minimum. So we need to state a measurable target. For example, we can say, The Radio shall consume less than 50 watts. The act of quantification is even more important in making sure that the quantity can actually be measured. It behooves of the designer at this level to think seriously about their requirement. Not just say, it should be as light as possible, as small as possible, generate as little heat as possible, and so on. At the very least, quantifiable bounds must be stated. Or else, the requirement can't be verified. There are other vague words that are just simply ambiguous, significant, typical, sufficient, adequate, appropriate, efficient, effective, routine, common, etc. Again, the presence of these words normally indicates that the writer has not bothered to consider what is actually required. So for example, The Radio shall conform to best practices for spurious emissions. Best practices are irrelevant, they're open to interpretation, and they're arguably in the eye of the beholder. So what we need to do is state a specific measurable level, and a specific reference must be made to a standard that describes that best practice. And somebody might say something like, The Radio shall limit Spurious_Emissions in accordance with Clause 7 of Standard XYZ. Note that we also made use of the glossary to be specific about what is meant by spurious emissions. In addition to introducing ambiguity through the use of vague words, confusion in the mind of the reader can also be introduced by using superfluous words. That is words that aren't necessary and actually take away from the meaning of the statement by hiding their true meaning. For example, we often use the construct, shall be able to. Now, unfortunately, this introduces ambiguity into a requirement. For example, The Record_Subsystem shall be able to store the location of each Line_item. But requirements are unacceptable because be able to can imply that the record search system doesn't currently have that capability but might be able to do it in the future. So for example, if we went to inspect the records subsystem and it cannot record the location, then the acquirer might say, well, it doesn't meet the requirement. But the supplier might say, well, he doesn't now, but it will be able to, all you have to do is buy this extra piece of equipment. Such a requirement is ambiguous and can't be verified. So you should remove the superfluous words, and we would say, The Record_Subsystem shall store the location of each Line_item. Another flow of superfluous words results will include additional verbage associated with describing the purpose of the requirement. That's not to say that we shouldn't describe the purpose, the articulation of that purpose is very important and should be included in the rationale attribute but not in the requirements statement itself. So for example, The Record_Subsystem shall store the location of each Line_Item, so that the Line_Item can be easily located by Users includes the purpose of the requirement. The additional words should be removed. And it should simply read, The Record_System shall store the location of each Line_Item. Parenthesis or brackets are often indicators of the inclusion of additional verbage. So for example, when we say, The Record_Subsystem shall store the location of each Line_Item, so that the Line_Item can be located easily by Users in brackets, is unacceptable because it contains the unnecessary description again of the purpose but this time in the brackets. And so we should remove the additional words as before and say, The Record_Subsystem shall store the location of each Line_Item. Again, the articulation of purpose is very important, but it should be included in the rationale attribute, not the requirement statement itself. So there are a few rules we need to follow in order to develop good requirement statements. In the next presentation, we address more of those rules. So hopefully at the end of this second module, you're starting to become convinced as to why we need to be careful about the writing of requirements statements. In particular, we must be very careful about the words in the sentence that form the requirement statement. When defining a shared, contractually binding view, the words and terms we use must be carefully chosen so to ensure that all parties have the same interpretation of the requirement. Now, once again, please go back to the presentation until you're comfortable and confirm that you've absorbed the material by completing the module quiz. The quiz questions are great preparation for the test, because the test questions come from the same set of questions as the quiz. Or at least, the questions are very similar in their nature and depth. In the next module, we look at some more rules relating to the choice of words we use in requirements. See you then.
