© George Koelsch 2016

George Koelsch, Requirements Writing for System Engineering, 10.1007/978-1-4842-2099-3_2

2. What Makes a Good Requirement?

George Koelsch

(1)Herndon, Virginia, USA

Now that you understand why you need requirements and what happens if you do them improperly, you must begin in earnest to learn what makes a good requirement. First you must understand the fundamentals of a good requirement, including the proper form of a requirement and how to handle negatives within a requirement statement. The bulk of this chapter will address the attributes that make a good requirement. Then I will finish with how to deal with common errors in requirement statements.

Understanding Requirements

In Chapter 1, you saw some examples of requirements. A requirement was defined as a need, desire, or want to be satisfied by a product or service. Now in this chapter, you will examine the important elements of a requirement.

Wikipedia defines a requirement as “a singular documented physical and functional need that a particular design, product, or process must be able to perform.” (Wikipedia’s reputation may not be as strong as some other sources, but sometimes its definitions are very accurate.) Wikipedia also adds that it is a statement that identifies a necessary attribute, capability, characteristic, or quality of a system for it to have value and utility to a customer, organization, internal user, or other stakeholder.

Note

In Chapter 13, you will see a definition that is similar, reinforcing the similarity between requirement statements and user stories.

The Form of a Requirement

Now, let’s examine some of the key aspects of a requirement. It is a singular statement. One requirement will address a physical and functional need that the product must perform. Focus on that one statement. That is important. There will be only one need per statement. Of course, there is the need as well—a necessary attribute, capability, characteristic, or quality of a system. This is something you get from the stakeholder, whoever it may be. The third part is the product, process, function, service, app (we will default to the word function as a lowest common denominator in this book from now on).

Note

Obviously one requirement cannot do everything related to a need all in one statement. Multiple requirements are necessary to ensure all aspects of that capability are addressed.

Each singular (singular described part earlier) requirement must consist of these following three elements :

  • Function (function described part earlier)

  • Verb

  • Need (value to the customer, whoever that customer is, which varies greatly)

Now, deconstruct one of the requirement samples used in Chapter 1:

  • 2-1 (1-1) The BOSS Access Control Function shall allow an authorized user to access the system.

This requirement breaks down accordingly:

  • The BOSS Access Control Function = Function

  • shall allow = Verb

  • an authorized user to access the system = Need

The verb is absolutely critical. In all your work, the requirement statement must have the word shall as part of the verb to indicate that is it a required statement (aka requirement). Without it, it is not required.

There are different schools of thought on the use of shall, should, will, must, and may. The convention in this book, however, is that every requirement statement must have one and only one shall in it. That makes it a requirement. The other four words in the previous paragraph do not make it a requirement. They are called qualifiers. Statements with those as verbs are like the adjectives of a normal sentence; they are nice to have but not necessary.

Note

If your organization uses a variation on that, adapt accordingly.

IEEE also uses the shall approach . Similarly, the federal government, including the Department of Defense (DoD), typically uses shall. In their book Software Requirements, Third Edition, Karl Wiegers and Joy Beatty advocate shall because

We have seen the verb ‘will’ to be used statements of facts, ‘should’ to be a goal that needs to be achieved, ‘must’ to be a performance statement.

Furthermore, Requirement Experts Website, on October 2012, stated, “Shall is used to indicate a requirement that is contractually binding, meaning it must be implemented, and its implementation verified.” It also states, “Will is used to indicate a statement of fact.” In addition, it defines should as, “Should is used to indicate a goal which must be addressed by the design team but is not formally verified.” I agree with these definitions completely. Other sources reinforce them. Most projects use the same definition. May carries no force at all, and must really is not well defined.

Thus, use shall in every requirement (as shown in this book) unless you are on a project that uses a different approach to which you need to adapt.

Dealing with Negatives in Requirements

There are some rules that people will tell you about writing requirements. One rule, which does not fit well as part of the attributes, is that you should never write a negative requirement. Part of the reason some people use as justification is that you cannot state everything a system should not do, as the entire universe is infinite.

Now, look at an example:

  • 2-2 DRAFT The BOSS Sampling function shall not use more than ten percent of the raw data in a sample.

Usually, there is a better way to say a negative. For example, you could state the previous requirement as follows:

  • 2-3 The BOSS Sampling function shall limit sampling of the raw data to more than ten percent of the total.

There are other words you can use instead of no, never, not, or none such as prohibit, limit (as earlier), or some other construct.

Does that mean you would never use a negative? Purists would say so.

Real-World Note

As you will see in this text, I am not purist. I have spent too many years in the real world writing requirements. I have found the rule is more like the Pirate Code in the first two Pirates of the Caribbean movies: it is more of a guideline than a rigid rule.

Sometimes there is just no other way to write something other than with a negative.

OK, so what is an example?

It is hard to find good example, but having said that, here are some examples:

  • 2-4 The system shall not override user selected contrast and color selections as prescribed in Section 508. (United States Government. “Resources for understanding and implementing Section 508.” Feb. 2015, www.section508.gov/ )

  • 2-5 The system shall not disrupt or disable activated operating system accessibility features.

  • 2-6 If the search is too complex, the system shall not crash while executing a search.

  • 2-7 The system report generator shall not require a per seat license fee for every user .

Now, you will examine the many elements that are necessary to make a good requirement. This is different from the different types of requirements, such as security requirement or business rules to name a couple, but are the attributes that basically every requirement statement should have regardless of the type of requirement.

Attributes of a Good Requirement

The attributes of a good requirement are the following:

  • Accurate, or correct*

  • Atomic

  • Complete*

  • Concise

  • Consistent*

  • Does not conflict with other requirements

  • Does not duplicate with other requirements

  • Independent

  • Prioritized*

  • Realistic

  • Traceable*

  • Traced to a source

  • Unambiguous*

  • Understandable by stakeholders

  • Unique

  • Verifiable*

Some books you will read will show more and show less. Nothing is gospel here. These are teaching elements. The Institute of Electrical and Electronics Engineers (IEEE) standard 830-1998, titled Recommended Practice for Software Requirements Specifications, recommends the attributes marked with an asterisk (*) in the previous list.

Note

Modifiable is included in the IEEE list, whereas this deals with the ability to modify requirements, and this deals more with the document as a whole rather than an individual statement. They are correct, but you will examine the list of attributes as being associated with an individual statement.

This shows that no one really agrees on exactly how many attributes comprise a good requirement.

Real-World Note

Some books I have seen include thirteen attributes or ten or the same eight as IEEE depending on their focus. However, from a teaching standpoint, I tend toward a more comprehensive approach so that you consider as many aspects as practical. With time, this will become second nature for you.

At this point, all these various attributes may not be obvious, yet as you read further in this book, you will see the benefit of having a wider list of attributes than a smaller list. Gap analysis is one area that benefits from this expanded list. However, you will see more about that much later in this text.

When you are first starting out, you will want to review your requirements and check them against the list of attributes. Eventually, you will not need to think about it as it will become instinctual.

That said, you will examine each one of these attributes in the following sections of this chapter. You will see references to them throughout this book, as they are the foundation of everything you will do hereafter.

Some of these attributes you will see again, when you get to user stories later in the book, as well you should. Good requirements and good user stories should have attributes in common.

Here is the mnemonic to help you remember them:

A420090_1_En_2_Figa_HTML.jpg

This mnemonic is CUD CRUD and CAV, IT CAPUT. Clearly, it is not the best one ever invented, but hey, it is a method for you to try to remember them. It is not as elegant as ROYGBIV for the colors of the rainbow, or HOMES for the names of the Great Lakes. However, if this helps you remember the attributes, then this is a successful mnemonic. (If you want to be immortalized, you come up with a better one, send it in, and you can receive credit in the next version of this book. You will achieve your 15 minutes of fame.)

There is no significance to the order these attribute are listed in or to the order that they are examined. Each attribute has its own significance that you should understand within that context. Without further ado, onto these attributes.

Now you will examine each attribute individually.

Accurate

An accurate requirement is defined as a precise statement of the system’s capability, its inputs, its outputs, its interfaces, and how it interacts with its environment.

When crafting a requirement, the potential exists for not being precise or accurate. One obvious mistake would be if a user says they need the results of queries within five seconds of initiating a query and you wrote the requirement as follows:

  • 2-8 DRAFT The BOSS query function shall begin displaying the results of a query within 10 seconds of initiating a query.

You can see this statement did not accurately capture what was requested (ten seconds versus the needed five seconds). A simple misstatement of a metric is rarely the issue when not accurately capturing the need. More likely, it is an inaccurate translation of the need. For example, the user says they need the display of all the cards dealt out within six seconds.

What was captured was the following:

  • 2-9 DRAFT The BOSS Solitaire Dealing function shall begin displaying the first card within six seconds of activating the Dealing option.

What the user actually wanted was the following:

  • 2-10 The BOSS Solitaire Dealing function shall finish displaying the last card within six seconds of activating the Dealing option.

This is a simple example, but you get the idea. The first requirement deals with the start of the function, whereas what the user wanted, and the correct requirement, was the display of the final dealt card.

Chapter 9 will spend some time on how to tease out what the users really need. Chapter 1 stated how you are a translator. Getting what the users’ needs are accurately is a challenge. It takes practice .

Atomic

You need to define each requirement at the atomic level .

No, you are not going to get into nuclear physics; this refers to decomposing the requirement down to its lowest, logical level. Not only is it important to show what should be done (e.g., not have multiple requirements in one statement), but also you will see the explanation why. For a given system, you might see the statement that said this:

  • 2-11 DRAFT The BOSS Access Control function shall provide a display and print capability of the access control list.

For example’s sake, say for this system, there are ten such functions, and they all need the same print and display capability. Testing begins. Then you learn that the print capability does not work. That means all ten requirements fail, or 100 percent. However, when you break the statements into ten print and ten display requirements, only 50 percent of the requirements fail. You now know accurately what failed. Take the previous requirement and break it down as follows:

  • 2-12 The BOSS Access Control function shall provide a display capability of the access control list.

  • 2-13 The BOSS Access Control function shall provide a print capability of the access control list.

There is another reason why you should split the requirement into two statements. Following this example, say that the development manager has one person working the display functions and one person working the print functions. This way you have provided each with their respective ten requirements, rather than having to share the responsibility. You have allocated the requirements uniquely, as you should.

You should look for connecting words like and, or, nor, yet and but to remove by splitting requirements to individual requirements. You will learn about cases where you cannot split requirements in Chapter 6. Even in these, you can eliminate the conjunctions (those connecting words from grammar. Yes, the reason you went into engineering was to get away from English. Alas, you failed!).

Parent-Child Requirements

Another variation exists in decomposing requirements to the atomic level. This is the situation where you have a parent requirement that has requirements subordinate to that requirement, or child requirements. Here is an example of a parent requirement (the second requirements number after the 2-14 is the requirements number in this system’s set of requirements, which is included to show how a parent-child requirement should be numbered to show the relationship):

  • 2-14    3.1.1 PARENT The BOSS Authentication function shall require all users to authenticate themselves before they can use the system.

Because you need to explain what this means, you need to provide more information to completely describe authentication. Thus, you should add the following:

  • 2-15    3.1.1.1 CHILD The BOSS Authentication function shall require all users to enter a valid username.

  • 2-16    3.1.1.2 CHILD The BOSS Authentication function shall require all users to enter a valid password.

  • 2-17    3.1.1.3 CHILD The BOSS Authentication function shall require all users to enter a valid system domain name.

  • 2-18    3.1.1.4 CHILD The BOSS Authentication function shall require all users to enter a valid username, password, and system domain name in three tries or they are locked out of the system.

  • 2-19    3.1.1.5 CHILD The BOSS Authentication function shall lock out users for one hour or when reset by a system administrator.

Note

This last requirement is not a compound requirement that needs to be broken apart. Yes, it has an or in it, but in this case, either condition can be met to allow the user to try to authenticate again. Breaking them apart really would not capture the conditional aspect of this requirement.

Now, move onto the children of the original requirement. Each requirement stands on its own, as it should. The only real difference is that they are related to the first requirement, 3.1.1. You should also reflect this with the numbering scheme. Instead of numbering the second through sixth statements 3.1.2 through 3.1.6, you should use 3.1.1.1 through 3.1.1.5 reflecting that they are subordinate to 3.1.1. You will examine more about this in the “Traced to a Source” section later in this chapter.

Complete

This is an interesting and difficult attribute to capture, so you will spend some time on it. This is a value that addresses both the individual requirement and the entire set of requirements.

Completeness of an Individual Requirement

At the requirement level, is all the information necessary to define the function, the verb that describes what action it should do, and the result of that action that completes the description of the need?

Examine this example:

  • 2-20 DRAFT The BOSS Access Control function shall provide a display.

What should the system display? Yes, it’s a simple example, but it illustrates the missing data. Sometimes, as the last set of requirements where you looked at parent-child requirements, you should provide the complete set of data by providing additional requirements related to the particular topic. That gets into looking at the system description as a whole, which you will come back to shortly.

In the meantime, focus on individual requirements for now. You have a challenge to read each requirement you craft to determine whether it is complete. Look at the following requirement:

  • 2-21 DRAFT The BOSS individual radiation dosimeter shall capture exposure of 1000 rem.

You are not expected to be radiation experts; just accept that the statement has legitimate expressions of radiation exposure. (FYI, this radiation exposure is very significant, in fact, as it is likely to be lethal.) Nevertheless, you need to answer the question, is this complete? The answer is no. Why? This one statement by itself means there are many more requirements necessary to show all the values that need to be captured. The user said they needed an individual radiation dosimeter that captured up to 1000 rem. Thus, you might need to write the following 999 requirements:

  • 2-22 DRAFT The BOSS individual radiation dosimeter shall capture exposure of 999 rem.

  • 2-23 DRAFT The BOSS individual radiation dosimeter shall capture exposure of 998 rem.

  • 2-24 DRAFT The BOSS individual radiation dosimeter shall capture exposure of 997 rem.

And down to the following:

  • 2-25 DRAFT The BOSS individual radiation dosimeter shall capture exposure of 1 rem.

Clearly, this is not practical. While complete, do you really want to write it that way? Of course not. You could write it as follows:

  • 2-26 The BOSS individual radiation dosimeter shall capture exposures of a maximum of 1000 rem.

If so, then you need to write a requirement for the minimum value.

  • 2-27 The BOSS individual radiation dosimeter shall capture exposures of a minimum of 1 rem.

Of course, you could write it as one requirement as follows:

  • 2-28 The BOSS individual radiation dosimeter shall capture exposures in a range of 1 to 1000 rem.

That looks complete, correct? Well, yes and no. What is missing? What increments must the exposures be captured in? Well, you ask when the stakeholder, they say it in individual rem values .

  • 2-29 The BOSS individual radiation dosimeter shall capture exposures in increments of 1 rem.

Wait, you can write all that in one requirement as follows:

  • 2-30 DRAFT The BOSS individual radiation dosimeter shall capture exposures in a range of 1 to 1000 rem in increments of 1 rem.

So, should you capture it this way? The requirement is complete. Yes, but you should not combine them because this is not atomic as was discussed in the previous section. The reason is the range of values is one requirement, and the increment is another. In addition, these two values would require testing them in different manners. While you have not learned about verification yet, it helps to think about all attributes whenever you can.

Now, move on to another aspect of individual requirements. There are situations where you may have an incomplete requirement temporarily. In the previous case, the user said they wanted the individual radiation dosimeter from one rem to some higher number that he did not know and would have to check with someone else to get the upper limit. You should capture the requirement so it is not lost or forgotten about, as follows:

  • 2-31 The BOSS individual radiation dosimeter shall capture exposures in a range of 1 to (TBD) rem.

What is TBD? It stands for To Be Determined . In this case, some other expert is going to determine the upper maximum. The original stakeholder knew that 450 rem was a value of interest to people in the military battlefield, but the stakeholder did not know if that was correct so he or she deferred the decision.

If you have a TBD, that means the requirement is not complete. So, why do you even address it here? Because it comes up—a lot. In fact, back in the ancient days when REs did requirements documents on paper (yes, even before word processing), you had TBD sections with a work-off plan for all of them. A work-off plan is a listing of each TBD and how it will be eliminated, as well as when each will be completed if possible. Some books will recommend you do this. In fact, they would assign unique numbers to each TBD to aid in tracking. If you have more than a handful, this might be a wise approach to take. Once you get the information, place it in the requirement and, voila, it is complete.

There is a variation on the TBD called the TBR, which stands for To Be Reviewed . In the case of a TBD, the stakeholder did not know the value of interest; the stakeholder did not provide any value. What if this same stakeholder had guessed 800 rem but said the stakeholder was uncertain if that was correct and needed confirmation. In this case, the requirement would look like this:

  • 2-32 The BOSS individual radiation dosimeter shall capture exposures in a range of 1 to 800 (TBR) rem.

Notice that this includes the suggested value, as it at least gives some indication of a reasonable limit. Again, once you confirm the upper limit, remove the TBR, completing the requirement. These TBRs can be included in the TBD/TBR work-off plan.

Completeness of a Group of Requirements

How do you determine when you have completely described the system of interest? Look at Figure 2-1. The rectangle is the universe of everything outside the project of interest. The circle inside that rectangle is the project of interest.

A420090_1_En_2_Fig1_HTML.gif
Figure 2-1. The project inside everything it interacts with

The key is the boundary, the edge of the circle. Remember in Chapter 1, you read about the scope of the project, “…that means that the boundary between systems/services/functions/applications must be defined.” When you have described everything inside the edge of the circle and on the edge, you are complete.

Sounds simple, right? Yes, it sounds simple, but it is not in practice. You need to define every action, every need, all performance needs, design constraints, architectural constraints, policy constraints, environmental constraints, and all external system interfaces with all inputs and outputs.

If you have a self-contained system with no external interfaces, say a game like Microsoft Solitaire, you have it much easier. In many, if not most, cases, you will have other systems/apps to exchange data, which means you have a much broader stakeholder base. There is one additional complication in defining your requirements. If you require external interfaces to make changes, you may have resistance because of budgetary, political, or even egotistical reasons. This complicates your efforts significantly. Ideally, the first time you do this, you will have a mentor because this is the most challenging aspect of capturing requirements. During the discussion about collection of requirements, you will learn about this more.

Meanwhile, back at the project requirements focus, there are items to consider. Make certain you define any graphics well such as figures, tables, and diagrams labeled with all units provided and any other pertinent information provided. In fact, speaking of units, you always need to include them in requirements regardless if they are associated with graphics. A glossary is useful. You will hear more about this in Chapter 3.

Chapter 1 briefly touched on gap analysis. The focus of that emphasis is to capture the completeness of the requirements set. As mentioned, you will learn more about how to do this in Chapter 9 on collection requirements. Suffice to say, what you need to do is find all the missing capabilities. You have to ask yourself, as well as others, what things should this system do that have not been discussed? Sometimes, this takes a bit of creativity. Actually, this can make it fun as you can ask some questions you might not normally ask. For example, should you drop your smartphone onto concrete from 3 feet up?

The answer is that the phone company and their manufacturers would say no. Why? They want it not to be survivable to what users might consider reasonable. For the record, when the U.S. Army was developing radiation detection equipment, their sophisticated electronic equipment did have such a requirement. Why? Because soldiers might use these pieces of hardware in the field, in potential combat situations, and the devices might see some rough treatment. Think of the hardware bounced around in a vehicle as it jostles over rough terrain. It needs to be tough. Do you think laptops that can take that kind of treatment? No. If you think they can, Google hardened laptops.

Therefore, as a phone user, you want the following requirement:

  • 2-33 The cell phone shall perform all its functions after being dropped onto concrete from a height of three feet.

The next time you want to replace your phone, ask what models have been tested to survive being dropped. You might be surprised—and not necessarily pleasantly.

Next, continue investigating requirements that you should specify for all conditions that can occur. Do cell phones need to survive an electromagnetic pulse (EMP) from a nuclear weapon detonation? What is the likelihood that the cell towers would survive unless they were nuclear hardened? Probably not. Even if they were then, would there be a power infrastructure to support the towers? Not likely. Thus, you cannot expect our phones to survive if the infrastructure around them would not. Thus, EMP survivability for our cell phones is not a reasonable requirement. This is an extreme example, but when looking for “all conditions,” this gets to be interesting. You have to do what some people call “thinking around corners” so you consider items that normally do not occur. However, are conditions that your system, whether hardware or software, will operate? Think of the conditions a satellite has to operate in. They are much harsher than on Earth.

Examining or considering unusual conditions is interesting.

Real-World Note

I will digress just a bit to describe what someone did when performing my job before I became the test manager. This individual did the Butt Test. Now this is not something you will find on the Internet (I checked). What this person did when a new piece of code came in was to turn on the system, put the keyboard on the chair, and promptly plop down on it. Hence, the name Butt Test. Needless to say, I did not carry on this (insert your adjective here) test when I took over. The idea, I suppose, was to see what happened when a lot of different keystrokes happened at the same time. I do not know what any of the test results were nor, frankly, do I care. The reason is that I had no requirement to test this. Nor have I ever seen any other project with such a requirement either.

One aspect to think about in completeness is the data elements in the system. Find out what the users need, not what the designers and coders need to manage the data. That is for them to specify. When you collect these values, not only what are their formats, ranges of values, or other conditions, but why should it be part of the system, and how will they use it. Why collect someone’s Social Security number when all you are doing is delivering the Sunday newspaper to him or her? Do you think this does not happen? Oh, it does. You must understand how stakeholders might use the value.

Do not fall into the trap that you see the previous set of requirements list a bunch of values so you assume you need all these values.

Real-World Note

I spent five years as an industrial engineer, basically an efficiency expert. Our instructors taught us to question every fact we collected and to get each answer from at least two different sources. I am not advocating that you need to perform this type of validation, but the principle is important.

Make certain you understand why each value is important to the users.

For example, say you have a requirement in the older set of requirements like the following:

  • 2-34 DRAFT The system shall maintain an index key field for the person data.

Upon investigating, you find, in the old system, the system populated person data in three separate tables and the software needed a way to link the tables together. However, you cannot assume the same implementation in this new system (in fact, you learn later, they do it with one table, so there is no need for this field). This is not a valid requirement.

You need to consider error conditions under completeness. What kinds of errors do you want to prevent? In the past, users have asked for error checking of query statements, as they want proper formatting invoked before initiating the query. This saves the user from having to correct something before they wait for the system to reject it, sometimes taking a significant amount of time. In addition, users have asked for the capability for the system not to crash when a complex search was run (it happened, in fact with quite regularity).

There are a couple of minor items to consider. Like when you populate the requirements in a document, you should number all the pages. You will learn more about documents in a later chapter. Also, all requirements need to be uniquely identified. You will see more about this in a later section of this chapter.

You should specify all applicable requirements to achieve completeness. This is the toughest attribute to check. Just before you finish requirements definition, the one thing a requirements engineer dreads is for a user to say, “I forgot that I need….” This text will do all it can to help prevent this by preparing you satisfactorily.

Concise

What you want is requirements that are short and sweet. You have learned about not having compound sentences, which fits nicely into the concise attribute. The shorter the statement, the likely the easier it is to read. This means you are using shorter, more precise words and more active verbs.

Now, look at two options.

Here is option 1:

  • 2-35 DRAFT The BOSS system software shall maintain a unique sequence of numbers for each record associated with the person data so someone can retrieve the record based on these numbers.

Here is option 2:

  • 2-36 DRAFT The BOSS code shall assign unique numbers for each person record.

Clearly, the second option is better. First, the statement uses 11 words versus 29 words, and it employs more concrete words like code versus system software. Second, notice the statement dropped the phrase dealing with retrieval using the record numbers as that really is another requirement.

Another aspect of concise writing is the clarity that a good requirement should bring. A requirement should be understandable by a nontechnical person.

If a non-IT person saw the following requirement:

  • 2-37 DRAFT The BOSS SOA implementation shall follow OOP practices on all objects.

this person would clearly not know what that meant. Try to target every requirement for that type of person. That is not always practical. However, if a particular stakeholder asks for a need that you translate into one or more requirements, that person should be able to understand it. When administrative or systems people have requirements, these are IT people and they better understand technology statements, even if non-IT people do not. Thus, sometimes you will have to write to the audience. Maybe you do not even present the administrative or systems requirements to the standard stakeholders. That approach has worked well in the past. You are not withholding information; you just focus on those requirements and needs that affect these typical users. (OOP means object-oriented programming.)

Consistent

Consistent requirements complement each other. Here you will focus on consistent usage. For example, you must use consistent terms. Many of you may have heard of the Mars probe that was lost when the vendor who built it used English measurements when metric measurements were called for. Therefore, if a command was sent that said go X distance in kilometers, when it measured it in miles, the craft would have gone 60.2 percent farther. So, use consistent measurements in you requirements.

That also means within a particular grouping of requirements, use the same measurement. Here’s an example:

  • 2-38 DRAFT The BOSS query function shall return the results of a simple query against one table within two seconds.

  • 2-39 DRAFT The BOSS query function shall return the results of a complex query against ten tables within three minutes.

Instead, they should read as follows:

  • 2-40 DRAFT The BOSS query function shall return the results of a simple query against one table within two seconds.

  • 2-41 DRAFT The BOSS query function shall return the results of a complex query against ten tables within 180 seconds.

One reason is that someone reading the requirements may miss the difference of the unit of measure in the second requirements. This helps to prevent it.

In addition, how you refer to selection capability is important.

  • 2-42 DRAFT The BOSS print choices shall be offered from a picklist.

  • 2-43 DRAFT The BOSS print choices shall be available from a pull-down menu

Warning

Usually the two requirements are not written one right after the other. What happens when there are a few dozen or a few hundred requirements in between them (or if it was more than a thousand?). It is difficult to spot when you read through them. A way to check is to have a mechanism that you can filter on topics, and see this limited list on one screen. For example, when you view a topic in Microsoft Excel, you see the information much closer together, and it is easier to spot. Another technique is for you to set them aside and read them some days later, and you might pick up inconsistencies. Alternatively, having others review your requirements can help. It could be something simple in an airport system where one requirement says outbound and another time return.

This book touches on jargon, or the use of terminology in the next chapter, but you must use terms consistently throughout the document. Do not say query sometimes and search another, unless they have different meanings. Be careful here as some people may use the terms differently. Most people use search to be just that. However, one group of people use search when they want to research. However, when they are looking for something specific, then it is query, not search—even though they use the same search tool. Go figure.

Here is another example:

  • 2-44 DRAFT 3.1.69 The BOSS system shall accept dates in the mm/dd/yyyy format.

  • 2-45 DRAFT 4.3.2.13 The BOSS Data Entry function shall allow entry of dates in the format:

    • dd/mm/yyyy

    • mm/dd/yyyy

    • yyyy/mm/dd

Clearly, the second requirement allows three different formats, whereas the first one accepts only one. Wait, you say, the requirements cover different areas within the system. One is at the system level, while the other covers only the data entry function. Good point, however, the lower one conflicts with the top level. If you write the statements the following way, you could accept it.

  • 2-46 3.1.69 The BOSS function shall allow entry of dates in the format:

    • dd/mm/yyyy

    • mm/dd/yyyy

    • yyyy/mm/dd

  • 2-47 4.3.2.13 The BOSS Data Entry system shall be accept dates in the mm/dd/yyyy format.

Here the more restrictive is acceptable at the function level, whereas the system level is more general. That said, be certain that you confirm that the function level truly accepts only the single format and just is not a mistake.

Does Not Conflict with Other Requirements

Now, you need to understand about inconsistency between requirements. Look at a set of reliability requirements for a hardware system.

  • 2-48 DRAFT Each BOSS subsystem shall have a reliability of 0.990.

  • 2-49 DRAFT The BOSS system shall have a reliability of 0.950.

On the surface that looks reasonable. However, there is some missing information that masks an inconsistency. What is important to this inconsistency is the number of subsystems that are in series. In this example, you use the following formula, since all the subsystems have the same reliability:

R(system) = R(subsystem)^N(number of subsystems in series)

Note

We will spend more time on reliability so you will understand this better in Chapter 5.

Equation 1: R(system) = 0.990^10, which yields a value of 0.904

Clearly, you cannot achieve the specified system reliability. You have several options. Option 1 is you should consider changing the number of the subsystems. If you have five subsystems and calculate .990^5, you get a number of 0.951, which meets the second requirement. However, the designers say that is not possible.

The second option is to ask the stakeholders if they would settle for 90 percent reliability. They say no. Thus, the third option is to change the reliability of the subsystems. By changing the reliability requirement to 0.995, then you get a value of 0.951. In this case, the users accept the change in the requirement (who wouldn’t when they provide a better value?) and the designers say it is practical, so you agree on the following requirements for ten subsystems :

  • 2-50 Each BOSS subsystem shall have a reliability of 0.995.

  • 2-51 The BOSS system shall have a reliability of 0.950.

Not always is the inconsistency so number intensive. It may be more like the following:

  • 2-52 DRAFT The BOSS ranking subsystem shall be high, medium and low options.

  • 2-53 DRAFT The BOSS priority function shall allow critical, high, medium and low options

Are ranking and priority the same? Yes, in this case. Are subsystem and function the same? Yes, in this case. Are high, medium, and low and critical, high, medium, and low the same? Yes, in this case. Although these requirements happen to be consistent at one level, you can see that the terminology is not, which shows that you can have more than one inconsistency.

Now, examine another pair of requirements:

  • 2-54 DRAFT The BOSS New Phone App shall ensure I can use the phone based on a biometric.

  • 2-55 DRAFT The BOSS New Phone App shall be delivered to existing phones.

Assume from a design standpoint that the capturing of a biometric cannot be accomplished without some hardware change to a phone. Then, there is no way that existing phones that do not have that hardware can accomplish the first requirement. If it can be done with software, than these two are not in conflict.

Sometimes the conflict may not be so obvious. Take the case of the following:

  • 2-56 DRAFT The BOSS New Phone App shall provide state-of-the-art machine learning capabilities.

  • 2-57 DRAFT The BOSS New Phone App shall be delivered within three months to existing phones.

Here the problem is that machine learning as described here would not fit into, say, a 16GB smartphone. Thus, it will not occur within three months. Unless you know a bit more about the system in question and its memory, you might not catch this inconsistency. If uncertain, ask experts.

Does Not Duplicate Other Requirements

This inconsistency is a bit more straightforward than the last ones. Basically, the same statement is made in two different places. Given that you have hundreds of requirements (or thousands), this can happen. You may have heard the same requirement from two different sources, and you did not remember capturing it before. Or, and this is very likely, as on a bigger project there will be more than one requirements engineer, two (or more) people will capture the same requirements. It may be as simple as this:

  • 2-58 DRAFT 3.1.5.5 The BOSS priority function shall allow critical, high, medium, and low options.

  • 2-59 DRAFT 4.7.8.2.1The BOSS priority function shall allow critical, high, medium, and low options.

Did you notice how far apart the requirements numbers are? That can explain part of the problem.

Other times, slight inconsistencies can mask the duplication, as shown here:

  • 2-60 DRAFT 3.12.5 The BOSS print choices shall be offered from a picklist.

  • 2-61 DRAFT 4.1.1.18 The BOSS print choices shall be offered to the user.

You might have to spend some time looking through your requirements to catch these kinds of duplicates. This should become a step in your checklist of the steps you should take during the review of your complete set of requirements. How you organize your requirements is important. That may help capture these kinds of errors when they are close together.

Independent

By this attribute, there are two potential meanings for it. First, a requirement should be able to stand on its own. Second, a requirement should be independent of a particular implementation.

Stand on Its Own

To understand the requirement, there should be no need to know any other requirement.

  • 2-62 The BOSS Authentication Function shall require the user to enter a username, password and domain name.

This requirement has all three parts: the function, the verb and the action.

Now, examine an alternate statement.

  • 2-63 DRAFT It shall require the user to enter a username, password and domain name in that order.

What is it in this requirement? The author probably assumed it was “The BOSS Authentication Function,” but he/she should state it so, to ensure a requirement statement can stand alone. Instead, you should write it as follows:

  • 2-64 The BOSS Authentication Function shall require the user to enter a username, password and domain name in that order.

Real-World Note

This does happen; even I have done it when I was crafting a lot of requirements from notes or even business process descriptions. You are frantically cutting and pasting and words are flying around in your text, and you miss it (pun fully intended). I remember the days when I actually did physically cut and paste. Yes, I am a crusty old curmudgeon.

That is why you should always go back and read what you have written. Look for any such pronouns such as it, they, them, some, all, a few, and several. This list is not exhaustive, but you get the idea .

Implementation Independent

This potential violation is more likely, yet as a concept it can be more difficult to find. A requirement should not contain any unnecessary design and implementation information. You will come back to the word unnecessary. Why do you not want to specify a design? First, you are a requirements engineer. Odds are you are not a design engineer or system architect. Even if you have some training and experience as such, it is not your role to specify design. Why is that?

REs are to specify “what” you want the project to do, not “how.” You must leave the designing and architecting to those responsible for the architecture and design. In addition, you do not want to limit their design by locking them into a particular approach. They are paid the big bucks to do that, just like you are paid big bucks to be an expert at defining requirements. Therefore, you will let them do their job. Now, examine this next statement:

  • 2-65 DRAFT The BOSS Personnel Data Capture function shall store the personnel data in a text file.

Is this correct? No. Wait a minute, shouldn’t you specify that you want to store the data? Yes, and you should. The problem is with saying “…in a text file.” That is design, and that is the designer’s and/or architect’s decision. The requirement should read as follows:

  • 2-66 The BOSS Personnel Data Capture function shall store the personnel data.

Here is another one:

  • 2-67 DRAFT The BOSS Personnel Radiation Dosimeter shall be protected in a metal case to prevent damage by the soldier wearing it while going through normal activities in the field.

Is this correct? On the surface, it might appear to be. However, maybe a metal case might interfere with the passage of the particles that are meant to be detected. Again, you have restricted the designers. Therefore, you should write it as follows:

  • 2-68 The BOSS Personnel Radiation Dosimeter shall be protected to prevent damage by the soldier wearing it while going through normal activities in the field.

The metal case was taken out. Here is another example to consider:

  • 2-69 DRAFT The BOSS shall be developed using Java.

Ha, you say, this clearly is implementation specific. Yes, on first blush, you are correct.

When reviewing the requirements on a new project, I found just such a requirement. I asked the program manager if this was implementation specific. The PM told me that our project was an umbrella program that other applications would be including under our umbrella. The customer we were developing it for wanted a common development environment. Thus, this was a valid requirement.

A clarification is in order. Some requirements theorists say that this is a constraint, not a requirement. They mandate all constraints belong in a special section. With the advent of requirements databases, a special section (as in a document) is not as easy to do. You can organize requirements into sections somewhat by arranging them with specific unique identifiers. The point is that this is a valid need so you call it a requirement. For some projects that want constraints handled separately, you can have a special constraint field in your database and mark this following requirement as a YES:

  • 2-70 The BOSS shall be developed using Java.

Real-World Note

I have one more point to make about this requirement. I have used it as a question in requirements interviews. I state the requirement and ask the interviewee if it is valid. Most say no, that it is implementation. Only one in the dozens I interviewed answered it correctly as Maybe. Then I went on to explain why correctly, as a possible constraint. Therefore, if you ever encounter this question, you now have the right answer.

Naturally, as a beginning RE, you may not know where the boundary is between what is design and what is a requirement. This will come with practice. It also helps to read other requirement sets.

Warning

People write requests for change (RFCs) as a mechanism for modifying existing projects. In these documents or forms (whatever manner these RFCs come in), usually there is a “Requirement” section. The potential problem is that anyone can write these requests, not just REs: users, designers, testers, or even managers. Most of these people do not have expertise with writing requirements, let alone crafting good requirements. If users write these, remember that they are not requirements engineers and write what they want the system to be. Usually they say something like, “I want a pull-down to list all my choices” and so on. Know who is writing these statements. Unless you know that an RE wrote them, do not consider them gospel.

Prioritized

Priority is the importance of a requirement or a group of requirements.

Assigning a priority means assigning a relative importance like high, medium, and low. This reflects what you need to do with requirements. This helps alleviate the problem mentioned in Chapter 1 where a list of requirements with no other information gives the impression that they all have the same importance. They do not. Nor should you list requirements without some qualification to the importance. You should start assigning one of four priorities to each requirement. (You can use three, five, or whatever number works best for your project.)

There is a distinction between priority and rank. Priority is the level of importance. In this book, ranking is numbering within a priority. In other words, in what order should the critical priorities be worked off? Rank 1 should definitely come before rank 10.

The recommended four priorities are Critical, High, Medium, and Low. Other than the “critical to life” needs, those items that are necessary for the project or the rest of the functions to work all are critical. For example, in the radiation dosimetry project, collecting the radiation exposure is critical, or none of the follow-on functions will work. You should apply the same approach to a software application. Without collecting and/or ingesting data into the application, none of the manipulations of that data will work. Those are the critical functions .

Note

In Chapter 5, the text will use Critical and High functions in one of the definitions there, so having defined priorities proves useful there to help identify those functions.

Many High functions are the mission-essential functions that manipulate the data that the critical functions have provided. This would be analyzing the radiation exposure or querying the database. The Medium functions would be less important, say reports of data for management. The Low functions are the remaining items.

One word of caution when you get to Low functions. If stakeholders find functions that no one seems to understand, that begs the question why anyone wants them. Here you may be getting to functions that really do not add value. This is one of the reasons that requirements engineers need to review the functions that developers want to create, so they do not provide things that stakeholders and users do not need. Trust me, they like to do neat things and think they know what users want. Do not let them, at least without checks and balances. Run it past the users if you are uncertain.

Who makes the decision on these priorities? While you as a requirements engineer can propose these values, the responsibility rests with the stakeholders. Even if you propose the priorities, the stakeholders must review them. If you have thousands or even several hundred, you might group the requirements together so the stakeholders have fewer decisions to make.

Here is one set of example requirements with the priority provided after the statement:

  • 2-71 The BOSS Unit Radiation Dosimeter shall collect the radiation exposure during the unit’s mission. Critical

  • 2-72 The BOSS Unit Radiation Dosimeter shall display the real-time radiation exposure during the unit’s mission when activated by a user. High

  • 2-73 The BOSS Unit Radiation Dosimeter shall generate a display of the radiation exposure values over the unit’s entire mission. Medium

  • 2-74 The BOSS Unit Radiation Dosimeter shall generate a graphic display of the radiation exposure values over the unit’s entire mission. Low

Here is another set of example requirements with the priority provided after the statement :

  • 2-75 The BOSS Casualty Data Collection function shall allow an authorized user to enter each unit’s daily casualties. Critical

  • 2-76 The BOSS Casualty Query Collection function shall allow an authorized user to query each unit’s daily casualties. High

  • 2-77 The BOSS Casualty Report Collection function shall allow an authorized user to generate a report of all units’ daily casualties. Medium

  • 2-78 The BOSS Casualty Query Collection function shall allow an authorized user to generate a report of one unit’s daily casualties over a month. Low

The IEEE standard 830-1998 says that requirements should be ranked for importance and/or stability to indicate either the importance or the stability of that particular requirement. First, you addressed the stability of a requirement when you learned about TDBs and TBRs in the “Complete” section. You should accept that some requirements are more important than others. IEEE defines stability with how likely it is to change.

Real-World Note

Honestly, as I think back over my career, I never have really estimated that. Alternatively, for that matter, I am not certain how useful this aspect of the attribute would be. Part of this may relate to the age of this standard—1998, almost two decades old. The environment is much more dynamic now than it was in 1998.

In addition, you will see more later in this chapter and the book how requirements change over time and how to address that. Thus, you should not worry about this aspect, unless you encounter a project where the management uses it and insists upon it. Then follow their well-defined approach (assuming it exists). Beyond that, read the IEEE standard and other sources to learn more about it.

IEEE breaks requirements into four ranks: essential, desirable, conditional, and optional. Essential means absolutely needed, without which the system cannot function. Think of life-critical aspects of an application. The next highest level is desirable but not life-threatening or disastrous to the application. Conditional requirements would enhance the product but would not affect the application if they were not included.

Finally, optional requirements may or may not be worthwhile.

Why would you capture something that is optional? This gives the designers some flexibility. These elements would be included in the design after the coders implemented all the rest of requirements and resources still exist to finish these needs. Alternatively, sometimes when designers are working on higher-priority items, they can include these optional items with very little impact to their effort. You, as a user, get more bang for your buck.

Does that mean you should not identify essential, desirable, conditional, and optional? No, if you need to capture this information, do so. Whatever is necessary to manage your requirements, that is for you to do. You want to clarify the language used related to your project.

Wait, you said priority, not rank. IEEE said rank. Here you get into a language issue. In this text, ranking means assigning a rank number within a priority to each requirement.

While IEEE used rank, this text recommends performing ranking within priorities, so you want to consider that distinction. In fact, when you get to Chapter 13 later in the book, again you will see prioritizing (with the four values) and then ranking numerically within each priority. This helps with the backlog management.

Alan Davis in his book Software Requirements: Objects, Functions, and States uses annotated as the attribute instead of the IEEE rank attribute. This is used to clarify terminology again .

Realistic

Is each requirement realistic , possible, feasible, or doable (other words for this attribute) in the timeframe the program wants it? Here’s example:

  • 2-79 DRAFT The BOSS Venus Probe shall be able to hover at any altitude using anti-gravity pulse generators.

First, ignore the possibility that this is implementation specific. Assume it is an architectural constraint.

Note

It does not take a rocket scientist to know this is not realistic since we currently have no anti-gravity capability. Nor are we likely to have it any time soon. (I hope I am proven wrong. That said, I would much rather be pleasantly surprised rather than negatively so because we counted on such a breakthrough.)

However, if you had said the following:

  • 2-80 The BOSS Venus Probe shall be able to descend slowly in the Venusian atmosphere by using a parachute.

this is much more feasible as the atmosphere is much denser than Earth’s atmosphere, making a parachute practical. In fact, the Soviet Union and United States both have used parachutes in the past .

What about the following?

  • 2-81 DRAFT The BOSS Earth Internal Probe shall be capable to image the fluid interior of the Earth using positrons.

Current physics understanding and engineering capabilities says that this is not possible. First, there are not very many positive-charged electrons available. Second, this is not the right particle to use for this type of imaging (maybe neutrinos, but that is not state-of-the-art yet). Third, being an anti-particle, it would destroy itself when it hits its particle pair. So, no, this is not feasible.

  • 2-82 The BOSS Submarine Probe shall be capable to image underwater vehicles using sonar.

Watch any submarine movie, and it will validate this requirement.

What about software? How do you apply this rule? Look at the following statement:

  • 2-83 DRAFT The BOSS Chess Software shall be capable of beating a Chess Grandmaster.

Is this feasible? If you have read about Gary Kasparov’s two matches with the IBM computer Deep Blue, then you know that this is feasible, as the computer won the second match 3½ to 2½. (FYI, Gary won the first encounter 4 to 2.) Therefore, yes, it is feasible. What about the following?

  • 2-84 DRAFT The BOSS Physician Diagnosis Software shall completely duplicate all the diagnostic functions of a physician.

While machine learning is making tremendous strides in decision-making algorithms, it does not appear to be so yet. These types of applications are providing assistances to doctors, but only that—assistance. Remember that with the advances made in this field, the previous statement may date this book. For everyone’s sake, we as a people should hope so.

How do you determine whether something is feasible? That is the rub. If you do not have a good understanding of the technology, it will be a challenge. You can do research, say on the Internet, to find out capabilities and limitations of technology. You can talk with experts around you. You will find that developers, designers, and architects can be valuable resources. If they are not overwhelmed with work, you will be surprised how open they will be to share their knowledge.

Know that not every requirement will need to be scrutinized so. As you go through this book, you will recognize many if not most requirements are doable, because you have seen them done. Think about every application you have ever used, every device, or app on your phone and you will realize that you have a more extensive field of experience to draw from. In most cases, it is just common sense. If you use science-fiction books as textbooks, then you might miss the mark .

Here is an actual example. The stakeholder said that he wanted a biometric used to check every person who used the system. Unfortunately, this was not a situation where people would use a biometric to authorize people to use a system, a one-to-one match for each person. One-to-one matching would be using a retinal scan to allow you to enter a restricted area. The stakeholder wanted to compare the biometric against the complete set of people in their system, a many-to-many comparison. A many-to- many comparison would be at the airport where the TSA at U.S. airports are checking all people’s pictures (many) against their list of people on the “no-fly list,” also many. For this stakeholders request, he only had a server with networked workstations; he did not have that capability built into the system to do a many-to-many comparison.

Given what I described in the previous paragraph, what I did was capture the requirement. I told the stakeholder that what he had said was a valid need and a realistic requirement. I did indicate that the capability was not yet built into the system we were working on, so it would not be part of the first delivery. I did explain that doing a significant search against a large biometric database was intensive and may not run on our current hardware configuration. He accepted my explanation. A couple of years later, we had begun building the biometric capability into the system so that the requirement was feasible. How did I know this? I had been with the project for more than a year or so at that point, and I had a good idea of our current capabilities, as well as what we had planned for the next few years. Therefore, I could speak with some assurance that the requirement in question was doable. So—feasible.

Thus, making the determination, while challenging sometimes, it can be done. Trust your judgment, and validate when you are unsure .

Traceable

The IEEE standard 830-1998 defines the traceable attribute as traceability to an origin and to future development or enhancement documentation. If you look at their document, they do not differentiate between traceable and traced. This book, as do other texts (Software Requirements by Davis, and others), does make this distinction. Here, traced means pointing a requirement to a source, which will be covered in the next section. The first section will talk about traceability to subsequent documents here.

Traceability

Traceability will show what design specifications are written that address the requirement. Odds are, they will be one or more design specifications. In addition, the testers will write their test plans and procedures. Every requirement must have at least one design specification and at least one test procedure. If they do not, you have a problem, as you will be unable to verify that all the needs are met. Table 2-1 shows examples.

Table 2-1. Traceability for the BOSS System’s Authentication Requirements to Other Documents

Number

Requirement

Design Spec

Test Procedure

3.1.1.1

The BOSS Authentication function shall require all users to enter a valid username.

2.1.1a, 2.1.2, 2.2.2c

TP-3.1

3.1.1.2

The BOSS Authentication function shall require all users to enter a valid password.

2.1.1b, 2.1.3,

TP-3.1

3.1.1.3

The BOSS Authentication function shall require all users to enter a valid system domain name

2.1.1c, 2.2.2a, 2.2.2b

TP-3.1

3.1.1.4

The BOSS Authentication function shall require all users to enter a valid username, password and system domain name in three tries or they are locked out of the system.

2.1.1d

TP-3.1

Table 2-2 shows another example, separate from the BOSS system .

Table 2-2. Traceability for a Cell Phone System to Other Documents, Separate from the BOSS System

Number

Requirement

Design Spec

Test Procedure

4.7.2.1

The cell phone shall perform all its functions after being dropped onto concrete from a height of three feet.

4.7.2.1.1, 4.7.2.1.2, 4.7.2.1.3

PD-7.9

This is one of the easier aspects to do, just tedious. Some of the work you will do is not the most exciting part of the job. It is important that you do it nevertheless. You will also need to do it jointly with other members of the team. Sometimes, you will find you will force them to do their job when they did not realize they had to. That is satisfying when you actually influence the design and/or testing.

Traced to a Source

As mentioned in the preceding section, this deals with tracing your requirement back to a source. This may be nothing more than listing the meeting where a group of stakeholders met to define their needs .

Do you need to specify exactly who said it? Usually not. A description of the type of user, if you know, can be helpful. Do you need to know the name of the person, when they may not be there three years later when you follow up? No. However, if you know it was a lawyer in the legal department, or the HR rep, that will be useful if you need to follow up later.

Sometimes policy documents dictate a requirement. If so, state the policy, even to the paragraph number if you can.

What if you have a team of engineers collecting information from various sources (usually because the project is too big for one person)? You may need to validate other people’s requirements. This is always a good idea. It helps you learn as well as the person being reviewed.

In addition, you may discover someone who is not following the guidance provided here.

Real-World Note

I had an engineer who wrote a requirement that stipulated that our existing system needed to be rewritten as a Microsoft Access database. Here comes the most important question you can ask (which we will spend more time in Chapter 9)—why? Her rationale was that the stakeholder had asked for it. I must point out that we already had delivered the system to several other clients, which were several large WANs with an Oracle database. I asked why this particular customer wanted it that way. She said that their current system was written in Access and they would not have to do any transition recoding. So, with this smaller customer, for one WAN we would change the entire implementation (and the reduced capability of Microsoft Access versus Oracle)? I do not think so.

Thus, the source of a requirement is important. In addition, as discussed earlier, not just because it was that way in the old system either. Validate those requirements. How should you track the source? You should do so like in the previous section, as another field in your database.

See some examples in Table 2-3.

Table 2-3. Traceability for the BOSS System’s Authentication Function

Number

Requirement

Source

3.1.1.1

The BOSS Authentication function shall require all users to enter a valid username.

BOSS Security Manager

3.1.1.2

The BOSS Authentication function shall require all users to enter a valid password.

BOSS Security Manager

3.1.1.3

The BOSS Authentication function shall require all users to enter a valid system domain name

BOSS Security Manager

3.1.1.4

The BOSS Authentication function shall require all users to enter a valid username, password and system domain name in three tries or they are locked out of the system.

Network Administrator at administration meeting, June 4, 2014.

Again, Table 2-4 shows an example separate from the BOSS system.

Table 2-4. Traceability for a Cell Phone System Separate from the BOSS System

Number

Requirement

Source

4.7.2.1

The cell phone shall perform all its functions after being dropped onto concrete from a height of 3 feet.

Every person who has dropped a cell phone!

Unambiguous

This attribute, dear reader, is the most difficult one of the 16. You will spend more time trying to get it correct, and in spite of this, you will have continual challenges with it. Even after doing this for more than 30 years, I still have to work hard at this. It has gotten better, but it never goes away .

Ambiguity in General

Let’s look at ambiguity in general and why it can challenge you. Unambiguous means that a knowledgeable person interprets each requirement statement only one way. In this case, a knowledgeable person is someone who is a stakeholder or user of the system or will be involved in the project in some way, so they will have knowledge of the system. An English literature major being exposed to Einstein’s theory of relativity will likely not be a knowledgeable person on that subject.

Honestly, this particular attribute will cause you more issues in your career than any others, possibly combined. Why? First, English, despite all those (usually in the humanities) who will tell you that it is precise, it is not. Have you ever had an argument with someone when upon further examination (usually after heads have cooled off) that you learned that what each of you said was correct, just that you did not agree on the meaning? That is why this text contains a chapter devoted to language and how to mitigate its flaws. Look at a dictionary. How many words on a page have only one meaning? That right there is part of the problem—the complexity yet beauty of the language.

Real-World Note

I was at a conference once where I was talking with someone from Australia, and he said, “You Americans use the word oversight wrong.” He emphasized the second syllable to mean a mistake by missing something. The context used in the previous presentation was oversight with emphasis on the first syllable to mean someone watching over something. Both definitions are correct, but context was so important.

How do you fix this?

There are those who advocate the use of something more precise like mathematics or models developed for the software and hardware development environment. You will see more why this may not be as effective as these IT theorists advocate in the next section on getting the stakeholders’ buy-in.

Note

Given that models have limitations for requirement uses, you will see a survey of some of these tools for you to get at least an understanding of them and can consider them when appropriate.

Thus, you will continue to examine using words as precisely as you can. The first thing you can do is find any words that can have multiple meanings. When you find them, put them in the glossary to define which one you are using. Now you cannot have hundreds or thousands of glossary terms. One way to cut this down is to use a specific phrase rather than two or three individual terms to reduce the number of entries in the glossary.

Realize that the stakeholders can review the requirements to help ensure that statements are unambiguous. Remember that they have particular institutional knowledge that the developers, who many times are in a different office, may not have. Thus, there may be a different understanding of the words.

One of my last projects had a group of developers who had no knowledge of what the stakeholders did. I had worked on defining the requirements for two years before the developers began looking at the requirements and found it almost incomprehensible because they did not understand what the users did. It was a difficult learning curve for them. We gave them training and had our subject-matter experts (SMEs) talk things over with them to clarify what their business process was. It wasn’t because the requirements were wrong or that the developers were dumb; it was like trying to read a foreign language without the translating dictionary. Ideally this is the worst case; it was for my career.

One point new ambiguity occurred was during the transition from a document-based set of requirements to a database set of requirements. That spawned an additional problem that had not existed before. The document used acronyms and abbreviations—well, the best way to describe it was an epidemic. The military and most of the rest of the federal government uses, and will always use, that shorthand. It is the language of a project and an organization. I will talk learn about it in Chapter 3. However, they have been used in this text. The policy was that the first time you used an acronym, you spelled out its meaning the first time and then put the acronym in parentheses. After that, in the document you just used the acronym. This saved time and space .

In documents, that was no problem as people read them sequentially. However, with the advent of the database, that was not always the case. A developer would not necessarily look at the complete set of requirements, and if he/she did not see that SME was spelled out two paragraphs before (like here), then he/she might have missed the meaning.

How do you overcome this? Spell out the acronym the first time you use it in a requirement, and if used again, then use the acronym. While that flies in the face of the conciseness that acronyms buy for us, it overcomes the potential ambiguity issue.

You can fall into other traps. For example, look at the following:

  • 2-85 DRAFT The BOSS Personnel Data Entry Function shall allow the entry of a name that is up to thirty characters long.

Is that valid? For two reasons, no. First, is that the first name, the last name, or the whole name? What if it is a Russian name, including the patronymic (middle name)? Will 30 characters be enough? In addition, it is best to break the name into parts, like first name, middle name, and last name. Wait a minute. What if it is someone hails from Latin American or the Middle East where there could be four parts to a name? You have to look at the range of names you could have.

Second, what do you mean by up to 30 characters? Do you allow exactly 30 characters? If so, say “up to and including 30 characters.” If it is more than 30, are those beyond 30 discarded? Does the user get an error message? You need to clarify this.

Look at the following requirement for another example of a different kind of ambiguity:

  • 2-86 DRAFT The BOSS Personnel Data Entry Function shall only allow the user to display one record.

Does this mean that only one record is displayed? If that was the intent, it does not say that. It means the display is the only option available to the user, no add, no update, no delete, no print, nothing but displaying the record. This shows that misplacing one word can give the wrong requirement. Reword it as follows:

  • 2-87 The BOSS Personnel Data Entry Function shall allow the user to display only one record at a time.

If the intention was to restrict the actions of the users, reword it more clearly.

  • 2-88 The BOSS Personnel Data Entry Function shall allow Read-Only user to only display records .

Subjective Terminology

Subjective terms also can be difficult. Here is a requirement that was actually written by someone (granted in the late 1980s but written nevertheless):

  • 2-89 DRAFT The BOSS shall be user-friendly.

You can run into a lot of subjective words that everyone will have at least one different interpretation. The previous alleged requirement falls into that trap. One way to determine whether something is subjective is to try to define a way to test it. If you cannot, then it is subjective. Alternatively, if you could think of more than one way to interpret what it is, it is ambiguous. This alleged requirement begs the question, what is user-friendly? Each person you talk to would define it differently. They envision the user interface differently. The solution is to write a requirement like the following:

  • 2-90 The BOSS shall follow our Organizational User Interface Standard.

Of course, that standard has to exist already. You will spend a little more time on user interfaces in Chapter 10.

There is a plethora of words that fall into the subjective (hence ambiguous) trap. This includes any word that ends in ly, such as the following:

  • Accurately

  • Adequately

  • Effectively

  • Efficiently

  • Expandability

  • Quickly

  • Robustly

  • Safely

  • Timely

Even taking the root word, like accurate, does not eradicate the issue. Each work requires a specific statement that defines what accurate means. Here’s an example:

  • 2-91 The BOSS radiation dose rate meter shall capture exposures with a minimum accuracy of 0.1 rem per second.

Is this easy to do for every one of these potential words? No. It is necessary, however, to ensure the statements are unambiguous .

Other sources will tell you to fix problems with unspecific words like acronyms, and/or, TBDs, etc., and so on. Earlier in this section, you saw how to fix acronyms and how to fix TBDs discussed the Complete attribute. Now, for the phrase and/or that has been used this in this book, even this chapter. For example, earlier, this chapter said the following, “That is design and that is the designer’s and/or architect’s decision.” Look at the last six words.

“…the designer’s and/or architect’s decision.”

It could mean the following:

“…the designer’s and architect’s decision.”

Alternatively, it could mean the following:

“…the designer’s or architect’s decision.”

However, the convention in this book is that it means both statements are potential true. Therefore, if it shows up in a requirement, both ways have to work. Most projects have used this definition. So, when you are on a new project, find out if this is the case. If there is no preference, add it as a project convention.

Etc. and so on used in a requirement means there is missing information. If you do not have all the options, actions, data elements, or choices, use TBD and follow the guidance from the Complete attribute .

Troublesome Parts of Speech

You can run into vague words (in addition to adverbs, those ly words) like the following (this list is not exhaustive):

  • Complete

  • Derive

  • Exhaustive

  • Maintain

  • Manage

  • Handle

  • Support

You will need to spell out what the word means, such as “maintain means add, change, delete, read, and print.”

You have to avoid indefinite pronouns. Here are some examples:

  • Almost

  • Any

  • Anybody

  • Anything

  • Few

  • Just about

  • Many

  • Most

  • Much

  • Several

  • Some

  • Somebody

  • Someone

Consider the following candidate requirement:

  • 2-92 DRAFT The BOSS radiation dose rate meter shall capture as much radiation exposures as the user experiences during a mission.

What does as much mean? What number should be considered, 1 rem/second, 5, 22, or 2897? You must be specific. You have already said the minimum of 0.1 rem/second. You should specify the upper limit.

  • 2-93 The BOSS radiation dose rate meter shall capture exposures with a maximum accuracy of 100.0 rem per second.

This is good because now you have given the full range, the upper and lower values.

You may be tempted to use modifying phrases:

  • as or if in front of:

    • Appropriate

    • Needed

    • Necessary

    • Required

  • Shall be considered

What do any of those phrases mean? It means the list is either incomplete or you are not certain if all the items in the list apply. Be specific, or add a TBD or TBR to the requirement and then work off that TBD or TBR.

Passive Voice

Last but not least, you need to consider passive voice. With passive voice, the subject of the sentence receives the action of the verb rather than performing it. Here’s an example:

  • 2-93 DRAFT The Social Security number shall be entered by the user.

Alternatively, here’s one even less specific:

  • 2-94 DRAFT The Social Security number shall be entered.

The first statement demonstrates an example of passive voice.

Using the active voice, it will read as follows:

  • 2-95 The user shall enter Social Security number.

The big difference is the change from shall be entered to shall enter, which is more active with the verb be removed and more concise, as it has one less word and four fewer letters. In fact, the sentence went from ten words to seven. This gets the requirement even more concise, the fourth attribute for a good requirement.

In the second example, who should enter this code? Should the system use machine learning because it should know all the Social Security numbers (SSNs) for every user? That might work if it is internal to a company. In fact, that would be a very good requirement. Alternatively, should the user enter it? The statement is unclear. Make it clear by specifying who enters it.

Note

I have to admit that I fail to write in the active voice in every shall statement. In fact, if you look through this chapter, you may find some examples. In those cases, I was attempting to make a teaching point, or the requirement structure may dictate passive verbs.

An organization’s style may drive you to passive statements sometimes, so watch for it.

Real-World Note

I will finish up with a situation that happened to show an odd example of how active verbs were involved with me. Some years ago, I wrote a transition plan for a new application that we were preparing to replace a legacy system. As part of that effort, I drafted the plan and then sent the document out within my organization for review. Another person had a comment on the document where she said, “It needs more active verbs.” Not only was I a little surprised by this, because the style of the organization was to not attribute who would do something, therefore forcing passive voice more than I liked to do. That said, she even had a list of active verbs she recommended that she passed to me—in the meeting, in front of everyone. I had one of my buddies come up to me later and said, “I could not believe you did not go off on her.” I did not, as you cannot. If you do, it only gets you a reputation that you may not want to have. However, I did a little investigation. I looked at her list, and I had included all of her verbs except one, procure. In addition, it made sense that I would not use that one since by the transition to production phase, everything had long since been procured. I then looked through the first three of my seven sections (it was a long document and I did not need to be exhaustive) to find the active verbs I had used that she had not considered. My list was comparable to hers. Therefore, I wrote her an email with my findings. I explained about her list and gave her my list. My point with this anecdote is that active verbs versus passive verbs is a question of magnitude. A purist will say that you should have no passive verbs. However, when you have the other attributes to follow, passive verbs sometimes work better.

Understandable by Stakeholders

While the previous attribute is the hardest to achieve, this attribute “understandable by the stakeholder” is the absolute most critical of all the attributes. If the stakeholders do not understand what you have written, you will never move to the next phase, because the stakeholders will not accept the system—ever. Interestingly enough, trying to get the requirement “unambiguous” and “understandable by the stakeholder” may sometimes be mutually exclusive. English, despite what people will tell you, is not a precise language. Mathematics is a precise language. Why do you think all the scientists of the world (and probably universe) use it instead of any other language? Alas, you cannot write requirements in mathematics. (Hm, unless some smart person discovers a way to do so…but that is a digression.) That is why some people advocate using modeling and/or Extensible Markup Language (XML) or Unified Modeling Language (UML) to get more precision.

However, gentle reader, your stakeholders are not mathematicians, may not be able to follow various models, or read XML or UML (more about this in Chapter 12) because these techniques are rigorous and most of your stakeholders are not prepared for such rigor. Does that mean you have the wrong stakeholders? Absolutely not. They are where they are for a reason. They are the users of the system; they are the resident experts at using the applications to do their jobs well, which they do; and they are the managers of those people. If they were IT people, they would be in the IT department.

So, what is a requirement engineer to do?

Write, early and often. And listen. Listen intently. You have to listen to what people say when you interview them, when you sit in meetings with them, and when you read their e-mails and documents complaining about their problems. You have to read how they say things. See what is missing. By that, what terms are they not using? That will help you understand the technology terms that they do not know. Sometimes, you have no recourse but to teach them the new way. However, keep that to an absolute minimum when you are writing your requirements.

The Collection phase in Chapter 9 will examine this in detail; you will learn to listen carefully, and by getting the users engaged in the process, you will establish a rapport. Do not destroy that rapport by writing requirements that they do not understand. Once you lose them, it is very difficult to get them back.

Real-World Note

Some years ago, I was meeting with the stakeholders, the people who would be actually using the system, not the managers who these people would report to who had a passing interest in the application. We had been discussing various requirements. One of the stakeholders gave a very emphatic requirement that they wanted us to meet. I had a junior requirements engineer with me who started to say that an International Organization for Standardization (ISO) standard made the requirement invalid. I put my hand on his arm to stop him talking before he completed his statement. I said, “This is your system, so we will do what you want. This standard does not apply to your situation.” That stakeholder had his hand up with his finger pointed at me, as if to argue vehemently why we must do it. He stopped his finger in mid-jab, and said, “Oh.” It was obvious, he expected an argument, and he did not receive it. There was a brief pause, and then we continued in a most congenial environment. I had listened very carefully to their real need and did not let some perceived standard stand in the way of capturing what they wanted. In this case, it dealt with some disputed territory that the standard violated their sovereignty. I established a rapport with them. I never had an issue working with these people thereafter.

Since you will write your requirements in English (or whatever language you use), you will need to be grammatically correct. Honestly, if you have difficulty even writing one sentence, you may want to rethink this as a career path. Alternatively, if you think you are OK since you will manage the whole team and will not need to write requirements, you are sadly mistaken. You will be writing a lot of other things instead, like reports up the management chain and people evaluations, both subordinates as well as your own. In business, you need to be able to communicate, both verbally and written. If you have a challenge, fix it. Take classes and practice.

Part of the challenge to making this attribute work is that for you to succeed here, you may have to compromise some of the others, succinctness for example (aka conciseness). You may need to spell it in a bit more detail to convince the stakeholder what you mean. As stated at the beginning of this section, it is critical that you convince the stakeholders, so do whatever is necessary to achieve that, even if you must compromise on conciseness or other attributes. Thus, succeeding with this attribute will go a long way in mitigating the requirements problems. That is the payback for making requirements that the stakeholders understand and therefore accept them as their own.

Unique

Unique refers to not only that the requirement statement itself is unique from every other statement but also that reference to each statement is unique. If you have met the “do not duplicate” attribute, you will have unique requirement statements.

Thus, this is probably the easiest requirement attribute to achieve—providing a unique identifier. This allows you ease of finding and referencing a requirement.

You have seen several examples throughout this chapter, references like a number such as 4.3.1.7 or an alphanumeric such as QUE-103. This text does not recommend one approach over the other. That said, you will need to check your requirements tool as it may dictate what you can and cannot have. (Don’t you hate dictatorial software?) There is one potential trap regarding numbers.

Something as simple as numbering requirements has risks? Yes, and here it is. Some people assign a group of numbers by functional areas before they start crafting their requirements. It might look like QUE-101 to QUE-200 for query requirements and RPT-1301 to RPT-1400. (We do not recommend this approach.) However, if you must, say because it is already instituted, here is the trap. What happens when you have 253 query requirements? You have not allowed sufficient space. So if you must do this, allow more numbers than you ever anticipate. Then multiply that number by at least 2 to ensure you cover all contingencies.

Wait, you might say, this text has not provided any examples of requirements written uniquely. Given how the text presented them, yes it has. Look at the requirements attribute, traced to a source, and you will see four examples that are uniquely written with unique identification.

As I said, this is an easy attribute. The best attribute was saved for last, one that is not as easy.

Verifiable

You must ensure that the developers accomplished what the users need. The key word here is verifiable. Many people will use the term testable. They are incorrect. Testing is only one aspect of verification, which can be accomplished by the following means:

  • Testing

  • Demonstration

  • Inspection

  • Simulation

  • Analysis

You can remember this with mnemonic STAID. (No, this has nothing to do with the word staid or its meaning of sedate. Nor does it have anything to do with the character of a requirements engineer. It is important to put that to rest very quickly.)

Now, on to the discussion about each one of these types of verification. Wait, why do REs need to go into the specifics of the types of verification? For a couple of reasons. First, on many projects, you will need to propose a candidate verification method for each requirement. You are not going to define how to verify it; just choose a method. Naturally, you should work jointly with the test lead. Alternatively, at worst, after you have proposed a draft, have the test lead review your proposals.

Second and more importantly, you need to know these types of verification so that you can make a reasonable assessment regarding the verifiability of your requirements. You need to look at a definition of each one of the following:

  • Test: A measurement to prove or show, usually with precision measurements or instrumentation, that the project/product complies with requirements.

  • Analysis: A quantitative evaluation of a complete system and/or subsystems by review/analysis of collected data.

  • Demonstration: To prove or show, usually without measurement or instrumentation, that the project/product complies with the requirements by observation of results.

  • Inspection: To examine visually or use simple physical measurement techniques to verify conformance to specified requirements.

  • Simulation: Executing a model over time to simulate a portion of the system.

Now, here is an example of each type of verification.

Testing

This is by far and away the most common form of verification.

Here is a sample:

  • 2-96 The BOSS Query Function shall generate results within 2 seconds of entry of the query 80% of the time.

  • 2-97 The BOSS Query Function shall generate results within 30 seconds of entry of the query 100% of the time.

The previous definition said that test is a measurement to prove or show, usually with precision measurements or instrumentation, that the project/product complies with requirements. Clearly, the example is measurable to determine whether the requirement is met. Notice this example gave a value less than 100 percent of the time; you need to give some upper limits. Obviously, with an example for 99.99 percent of the time, it begs the question what happens that last 0.01 percent of the time. If you never specify anything, then a developer might think he has an infinite time to complete that last percent. Never give them an out.

Real-World Note

I had a developer tell me that because the requirements document did not explicitly state that February 32 was invalid, he did not need to validate dates. He was categorically wrong as an older version of the requirements document did have it listed, but it shows you how silly some people can be. The person was being absolutely serious. You cannot make this stuff up.

Inspection

The previous definition said that an inspection examines visually or uses simple physical measurement techniques to verify conformance to specified requirements. Now, look at the following example:

  • 2-98 The BOSS Query Function shall generate its queries using a SQL server.

Note

SQL = Structured Query Language.

Accept that this is a valid requirement (some may argue that point, but there are instances that it applies—for organizational or architectural reasons). In this case, you need a way to see the query statements generated by BOSS, and by looking at it (examining) you can determine whether they are SQL statements or not.

The inspection may be as simple as looking at just one element to pass the requirement. For example, in the following requirements

  • 2-99 The BOSS Central Code module shall have the name of the vendor who wrote it.

all you have to do is look at the code for that single module and see whether the vendor’s name exists. If so, the requirement passed.

Now back to the earlier SQL statement requirement, which may take a great deal of inspection to ensure the full spectrum of SQL statements is addressed. This could take dozens or more inspections, depending how they are generated.

Another example that is more frequent with hardware development is shown here:

  • 2-100 The BOSS computing device shall have a Universal Serial Bus (USB) port for connecting external devices.

All you have to do is look at the outside of the device to see whether a USB port exists. Naturally you will have to verify that it operates, but that would be additional requirements.

Demonstration

A demonstration proves or shows, usually without measurement or instrumentation, that the project/product complies with requirements by observation of results.

As a follow-on to the last requirement in the previous section, examine the following requirement:

  • 2-101 The BOSS computing device USB port shall allow the connection of a USB drive and recognize the files therein.

In this case, you connect the USB drive into the BOSS USB port, and if the BOSS displayed the files, you have demonstrated this requirement.

Simulation

The previous definition said that a simulation is executing a model over time to simulate a portion of the system. NASA uses this technique quite often to duplicate environments that do not exist on Earth or are hard to duplicate. Take a look at the following requirement:

  • 2-102 The BOSS Venus Probe shall survive 250 mph winds.

Earth does not have speeds that fast here naturally (thankfully). Therefore, a wind tunnel of significant speed would need to be built to test this requirement to simulate the winds. That does not mean you have simulated absolutely every detail, but as closely as practical. Of course, anyone who knows anything about Venus knows it has very high temperatures and crushing pressures to consider as well, but you were just examining one requirement.

For software, consider the following requirements:

  • 2-103 The BOSS Query Function shall handle an average of 50 users at a time with no degradation to query response times.

  • 2-104 The BOSS Query Function shall a peak load of 200 users for an hour with only twenty percent addition to the query response times during that hour.

You may be unable to get 50 users to test this, let alone have 200 people trying to test this. The best bet is to have a simulation package that duplicates the actions of a user to put the appropriate levels of stress to the system.

Analysis

Analysis is defined as a quantitative evaluation of a complete system and/or subsystems by review/analysis of collected data. You will verify the following requirement by analysis:

  • 2-105 The BOSS game device shall have a mean time before failure of 200 hours. (It costs $10, so don’t expect it to last forever!)

Here you would have collected all the run times of the ten devices you ran for two weeks straight without turning them off. Tabulate all the time they ran before they failed. Total the number and divide by ten. If the result is greater than 200 hours, the requirement passes.

Remember that you may have requirements where you stress the system by turning it on and off every ten minutes for the entire two weeks to see what that does to the time to failure. (Who and how they test that for two weeks 24 hours a day is for the test team to address, and they would suffer through the sore fingers.) You get the idea for analysis.

Code reviews are a form of analysis where other people on the team, or senior programmers, look at a developer’s code to see potential errors. For example, if coding standards exist, the code is analyzed against that standard. Standards help not only to eliminate bugs, but in the long run to ensure maintenance. Keep in mind that people do not stay on a project forever, so someone else may have to maintain it. Coding standards help with that transition.

Wrap-Up of Verifiable

A requirement is verifiable if there exists a cost-effective process with which a person or machine can check that the software product meets the requirement. Think back to that Venusian probe. If you had a test budget of $100,000 for the entire probe, odds are you could not verify the wind speeds, let alone the temperature and pressure requirements. In fact, you probably could not afford to build it, if that is the size of your test budget, but that is another matter.

Finally, nonverifiable requirements include phrases like works well, good, user-friendly (see the earlier example with this as an alleged requirement), and usually happen. These words cannot be verified because it is impossible to define the terms good, user friendly, well, and usually.

If a method cannot be devised to determine whether the software meets a particular requirement, then that requirement is not verifiable and either you should remove it or, most likely, you should revise it.

One More Attribute: Modifiable

You have examined 16 attributes for individual requirements. Granted, some have applicability to all or part of the entire group, like traceability. You might consider at least one more that you might hear about—modifiable.

Note

You may read about others in some sources, but they are most likely just different terminology for ones addressed here. Alternatively, you can consider them so minor as to not spend time here. You are trained well enough to determine whether their suggestion has merit.

The 830-1998 standard includes this one. It applies modifiability to both the individual requirement and the entire group of them. Every requirement is modifiable by very definition, so there is no reason to focus any time on it.

Modifiability with regard to a document or a group of requirements deals with how modifiable that document or database is. Organization is important, and breaking groups of requirements that have functional similarity is important. This supports a document’s table of content, index, and cross-references to other documents. Document organization will be examined in Chapter 7.

Capability Within a Requirement

Examine one more aspect within a shall statement. You will have seen the phrase “the capability to” in some of the requirements already shown as examples in this book. This is not an attribute of a requirement but a convention many if not most REs use. This phrase, “the capability to,” has a very specific meaning. It means allowing the user the option to do something. Here’s an example:

  • 2-106 The BOSS Access Control function shall provide a capability to assign an access control list to search results.

This means the user has the option to assign an ACL to search results. However, the user does not need to do it for every search result. Look at the following statement:

  • 2-107 DRAFT The BOSS Access Control function shall automatically provide a capability to assign an access control list to search results.

Does this make sense? Do automatically and provide the option go together? No, the system does not make choices every time. Yes, there could be rules where decisions are made, but those are specific rules, and the system is not really deciding but just following rules.

Usually the phrase the capability to is written as provide the user the capability to. There are developers who do not understand this. Therefore, it is your job as the RE to educate them. Sometimes this is easier than others.

Real-World Note

I had one program where they had been using the phrase for more than ten years for providing any capability of the system, not as an option. I realized it was not worth the effort to try to reeducate an entire team. Besides there were more than 1,000 requirements and it was not worth the time and effort to fix it for little value added, since the system was being replaced and these developers would not be part of the new system.

Types of Errors That Can Occur with Requirements

Capers Jones, on Dr. Dobb’s web site (see the “Reference” section), said there are three chronic problems with requirements.

  • Many requirements are dangerous or toxic and should be eliminated.

  • Some clients insist on stuffing extra, superfluous features into software.

  • Requirements are never complete and grow at rates greater than 1 percent per calendar month.

Dangerous or Toxic Requirements

First, you should learn what one of these kinds of requirements is. These are requirement defects that testing may not detect. One of the most prominent examples of a toxic requirement was the Y2K bug. Requirements for years had been written to capture dates including years. However, no one ever specified the format of the year. That was left to programmers who for decades, because of space considerations in storage (when it was very expensive), wrote the year as the last two digits. Instead of 1929, it was stored as 29. In the 1960s, when a program was written, no one worried about the year 2000 as it was so far away. However, after the year 2000, if the year was 29, would it be 2029 or 1929?

How do you prevent these? As was said, testing may not catch it as tests were written based on the assumption of the year as two digits. So, using formal reviews of requirements helps to eliminate them. Why? You draw from other people’s experience to recognize good requirements versus these toxic or dangerous ones.

Extra, Superfluous Requirements

This was talked about this earlier in the “Prioritized Attribute” section of this chapter. When all stakeholders prioritize and rank requirements, this helps to identify these. Even if people do not say, “I see no need for this,” others will push it so far down the priority list that it is not likely to ever be worked on.

Real-World Note

Some years ago, I was holding a meeting where we were ranking changes requested from the users. One of the newer people said, “If my change is considered a Low priority, even with a High ranking, with emphasis on working off all the High and Medium priorities, my change is likely to never be worked on.” Absolutely correct. That was when I knew the whole group of stakeholders really understood.

Incomplete Requirements

Studies have shown that requirements grow from 1 to 4 percent per month. This is where one of the major drawbacks came with the traditional waterfall method. The project would spend the beginning period of the project defining requirements and freeze them for the rest of the development.

In the Jones article mentioned earlier, he states that 15 percent is a good annual growth rate. Taking that as a conservative representation of reality, in six years, you will have doubled your number of requirements. If your program took that long, think how out of touch with the needs of the users you will be.

How do you fix that? Various methods evolved from the waterfall development methodology to ultimately (now, at least) achieving the agile approach where requirements are defined in detail just before the work is done. This helps with capturing the reality at that point. Then changes are considered as they are known. It may not be perfect, but it works considerably better than the waterfall approach. This will be discussed much more in Chapter 13.

Others

Several problems were discussed in the attribute sections, such as missing or wrong requirements, or ambiguity. In other readings, you may encounter discussions of misplaced requirements. This means a requirement is placed in the wrong section in the document. In Chapter 11, you will learn about management of requirements in a database. How is something misplaced in a database? By misplaced requirements, if you group like requirements (e.g., search, reporting, access) into functional areas and user access requirements are in the search section, that is what is meant by misplaced.

However, what if you have a requirement like the following?

  • 2-108 The BOSS Access Control function shall provide a capability to assign an access control list to search results.

You would think this belongs to the Access Control section. However, it also talks about search. Should it go there instead? On the other hand, should it be in both? You would argue that it may not be a big deal since a good database has searching and filtering that will allow you to find these when you need it. Never should it be in both, since that means you have duplicate requirements. Remember that.

References

IEEE-SA Standards Board. “IEEE Std 830-1998, IEEE Recommended Practice for Software Requirements Specifications.” Sponsor: Software Engineering Standards Committee of the IEEE Computer Society, Approved 25 June 1998, p4, 6-7, 8.

Wikipedia. “Requirement.” Feb. 2015. http://en.wikipedia.org/wiki/Requirement

Wiegers, Karl, and Joy Beatty. Software Requirements, Third Edition, Microsoft Press, 2013.

Davis, Alan M. Software requirements: Objects, Functions, and States. Prentice-Hall, Inc. Upper Saddle River, NJ, 1993, p191 to 193

United States Government. “Resources for understanding and implementing Section 508.” Feb. 2015, www.section508.gov/

Lou Wheatcraft. October 9, 2012. “Using the correct terms—Shall Will Should.” Requirement Experts. Feb. 2015, www.reqexperts.com/blog/2012/10/using-the-correct-terms-shall-will-should

Jones, Capers. “Chronic requirements problems.” November 26, 2012. The World of Software Development. Dr Dobb’s. Feb. 2015, www.drdobbs.com/architecture-and-design/chronic-requirements-problems/240012797

Exercises

Exercise 1

Examine the 16 attributes of a requirement and rank the order that you should accomplish them and why. Ties are acceptable. Maybe a flow chart or swim lanes might help depict it.

Exercise 2

For half of the 16 attributes, write an example hardware requirement for each one, ones that are different from those already provided in the book. Which half? Good question, and we don’t care. You can do the first eight, the odd numbers, the even number, or only the prime numbers. It is your choice.

Exercise 3

For the other half of the 16 attributes that you did not use in Exercise 2, write an example software requirement for each.

Exercise 4

Try to rewrite these requirements eliminating the negative from the statement:

  1. The system shall not override use selected contrast and color selections as prescribed in Section 508.

  2. The system shall not disrupt or disable activated operating system accessibility features.

  3. The system shall not use color coding as the only means of conveying information, indicating an action, prompting a response, or distinguishing a visual element.

  4. The system’s software shall not use flashing or blinking text, objects, or other elements having a flash or blink frequency greater than 2Hz or lower than 55 Hz.

  5. If the search is too complex, the system shall not crash while executing a search.

  6. When the system identifies spelling errors, the system shall not auto-correct without user acceptance.

  7. The system report generator shall not require a per seat license fee for every user.

Exercise 5

Write requirements to define what the customer wanted in Figure 2-2.

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
3.148.106.212