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).

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.

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.

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.

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!).

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 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.

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

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)

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.

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 .

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.

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.

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.

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 .

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.

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.

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.

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.

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.

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.

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.