Lists of Items in Requirements

The point of this section is to distinguish when to use lists of items and when to separate things into different requirements. If you remember in the discussion on the atomic attribute for a requirement, one rule said that you need to have only one statement per shall statement. “Have only one value” was never explicitly stated. Now, examine an example where you want to collect information on a person where the data you are interested in is as follows:

• First name

• Middle name

• Last name

• Street address with apartment number

• City

• State

• Home phone

• Cell phone

You want requirements to capture these values for the Person Collection Function . You could write each as a separate requirement, where you will have the following:

• 6-1 DRAFT The BOSS Person Collection Function shall collect First Name.

• 6-2 DRAFT The BOSS Person Collection Function shall collect Middle Name.

• 6-3 DRAFT The BOSS Person Collection Function shall collect Last Name.

• 6-4 DRAFT The BOSS Person Collection Function shall collect Street Address with apartment number.

• 6-5 DRAFT The BOSS Person Collection Function shall collect City.

• 6-6 DRAFT The BOSS Person Collection Function shall collect State.

• 6-7 DRAFT The BOSS Person Collection Function shall collect Home phone.

• 6-8 DRAFT The BOSS Person Collection Function shall collect Cell phone.

There is one drawback to this approach. Given that all these values should be collected at the same time, with them listed separately, you could lose this connection. Therefore, you should consider the following approach:

• 6-9 The BOSS Person Collection Function shall collect the following data:

  1. First Name

  2. Middle Name

  3. Last Name

  4. Street Address with apartment number

  5. City

  6. State

  7. Home phone

  8. Cell Phone

Does this fly in the face of the edict to identify requirements as atomic? Yes…maybe. Remember the reasons to capture requirements at the atomic level? First, capture the requirements down to the lowest possible level. What is the lowest level here? Is it the data value level, or is it the collection of data level—the data values grouped together? It is at the collection of data level. If you still are uncertain, then look at the other area you should consider. Would these values be worked on by different people, for coding and/or testing? Given that someone would probably code these on one screen or tab, they would be worked as a unit. In addition, a tester would test all the data as one test.

However, you argue, if the phone number fields do not work, then you have the quandary of only part of the screen/tab and the associated requirement does not work. You are absolutely correct. Phone numbers would likely be coded and tested by the same person. Therefore, these values need to be worked on together. That need overrides the atomic principle for requirements. If one of two phone numbers works, it is only partially satisfied. Thus, you do not follow the atomic principle in this case.

Is there ever a case where you should separate the requirement? Well, in Chapter 2 you saw the example of the “print and display” type of requirements. In that case, initially all the requirements were written as “The system shall print and display….” You need to separate all the requirements into one statement for “print” and another requirement for “display.” That still holds true. Therefore, what you have now are two ends of the spectrum. You definitely separate functions that are different, whereas you keep them together when they are small groups of data values that belong together. So, somewhere in between those two endpoints, you have to make a judgment call.

What factors should you look for that will help discriminate when to do one approach versus the other? This is a judgment call based on what we have discussed.

Now, look at another situation. The system needs to allow all users various accesses to the data within the system. Users will be able to read the data, add data, change existing data, and delete the data. Which of the two approaches make sense here?

Here is option 1:

• 6-10 DRAFT The BOSS Access Control Function shall allow a user to have an access to the data consisting of the following:

  • Read

  • Add

  • Edit

  • Delete

Here is option 2:

• 6-11 DRAFT The BOSS Access Control Function shall allow a user to have read data access.

• 6-12 DRAFT The BOSS Access Control Function shall allow a user to add data access.

• 6-13 DRAFT The BOSS Access Control Function shall allow a user to have edit data access.

• 6-14 DRAFT The BOSS Access Control Function shall allow a user to have delete data access.

One additional point is important here: a user could be assigned more than one access function. This points to a distinction: of the options are not mutually exclusive, that is another reason to combine them. For example, users who have access to add, edit, or delete data also should have access to read the data. So, someone may have read and add access; or read, add, and edit access; or access to all four functions. Thus, in this case, option 1 is the correct answer.

Consider also that there could be a variation on the add access function. Some users in the organization can suggest that a new person be added to the picklist, and one or more other users are able to approve the addition. So, when someone joins the team, a person who has Suggest rights can propose the addition of the person. The “suggester” proposes the name in a blank field at the bottom of the picklist. The name does not show up for everyone on the picklist until an “approver” accepts the name. If the “approver” rejects it (say because the person is only an intern who will go away in two months), then the name is not added to the list. In this example, you would add the two options, Suggest and Approve, to the requirement as such:

• 6-15 DRAFT The BOSS Picklist Control Function shall allow a user to have an access to the data consisting of the following:

  • Read

  • Add

  • Edit

  • Delete

  • Suggest

  • Approve

In this situation, you might need additional requirements to explain what role the Suggest and Approve actions would be.

Back to the earlier discussion of when do you use a list of requirements versus one requirement. What happens if the number of data values grows significantly? Ask yourself if it is likely they would be done on one screen or tab; then that may help to write one requirement. However, what you learned earlier said that you are supposed to write the requirements in a manner that does not limit the design. You are absolutely correct. Then the answer becomes a judgment call. Would 12 values on one presentation (screen/tab/etc.) be OK? Probably. Again, it gets to the stakeholder needs. Do the values need to stay together? If so, then the answer probably is yes, do one requirement.

What if the number of data values is 25 or 67? Now you see it gets much harder. Twenty-five maybe, again, if they are significantly related to each other. However, you really need to analyze whether they cannot be grouped in some way. Think of a medical history form where it asks if you have had any of several dozen conditions or diseases. If there are two groupings of data values, then you should have two requirements. As for the 67 data values, you really need to analyze it carefully. If you were adding a new person to your engineering company, in your HR department you would have a Personnel Branch, Payroll Branch, Retirement Branch, and Disciplinary Action Branch. In the Engineering department you have Software Maintenance Branch, Software Maintenance Branch, Branch, Hardware Maintenance Branch, Software Development Branch, and Integration Branch. Even though there are nine branches, you still would likely break them apart by departments, with one requirement for each department, and then list the branches as elements within the department.

There may be situations where it is difficult to break a significant list of values into groups. Look at that situation in the next section.

Lists of Data Elements

You will look at a series of data elements in a message. Messages are a technique used between systems. In the particular example, these messages are between a mission-control system and a space probe. Messages are either commands to the spacecraft or data messages back from the probe portion of the spacecraft. This is actually a simple example because only image data is collected. In the real world, messages can be much more complicated with very intricate values passed between systems. What will be used for this example will be long but the same kind of data repeated. Real-world examples could have variable records that are dependent on the data collected. This example will have image data and its location, with many repeated pairs of this data. Messages that are thousands of bits of data are not unusual.

Now, consider a message you want to send to and receive from a deep-space probe being planned to explore the trans-Saturnian planets. You have to specify the message format you are going to use to transmit commands and receive their data. The message for the probe’s collected data is going to be more than 2,000 characters long, with very specific formats and possibly many parts to it. No, this is not a real project, just one that was fabricated as an example. However, I have used very complex, long messages just like this. The reason for the length of a message is to capture a picture that has to specify either color or significant shades of gray and the location of each pixel.

Maybe before you examine the specifics of the topic of data elements, you need to have some background so you understand some of the points the stakeholders need to consider. In this case, the stakeholders are NASA. The first item to consider is how far away the probe will likely be.

Uranus (the closest approach the body will have to us) is 2.6 trillion kilometers.

Pluto (the farthest approach the body will have to us) is 4.2 trillion kilometers.

Given that the speed of light is 300,000 kilometers per second, it will take about 2.4 hours to send a message to Uranus at its closest and about 3.9 hours to send a message to Pluto at its farthest. Yes, that is hours, not seconds. Even going to the earth’s moon has about a 1.3-second delay. Therefore, a major factor is not waiting for a response before continuing a message. Thus, the message has to be complete, with a significant ability to check that the values are sent and received.

This example will not consist of the entire system here but will show some representative examples of messages. For this example, the system will send two types of messages to the probe, when in reality, there could be dozens or even hundreds of messages. The mission-control system will send a request for system diagnostics. In the other pair of messages, the system will send a request for the spacecraft to send an individual image captured from the imaging system on board. Yes, also, there could be other detectors from parts of the electromagnetic spectrum, not to mention telling what the probe should be sensing. This gives you the magnitude of what space probes may consist of, yet you will examine only two aspects to keep the example relatively simple.

You are going to consider the data element technique for requirements, where you create one requirement for each data element. You must capture the following attributes for each data element (as is appropriate, as you may not use all):

1. Requirement number

2. Field number/designator

3. Field name

4. Description of the field

5. Length of the field

6. Format of the field

7. Units of the field

8. Any special Information related to the field (ranges, selectable items, etc.)

What is a most important distinction from how you defined requirements for data elements before is the use of a requirement number for each one. The reason you do this is what was discussed at the end of the previous section; when you will have many values, you want each one tracked, especially given all the attributes you need to define for each data element. When the message is built and verified, each data element must be verified against each attribute of that data element. The discussion in the list of data elements was not that specific.

Now, examine the four messages.

Order of Steps in Requirements

What is the difference between order of steps and lists of items? You saw the list of items in the previous section. However, order was not important to those items. Those requirements were just related to each other. You will encounter situations where certain steps must be accomplished in a specific order. The sequencing of requirements is addressed in this section.

The section titles were chosen carefully. For some lists, like those discussed in the preceding section, sequence is unimportant. However, for a list of steps, the sequence or order matters. That means you have particular actions that need to be ordered in a specific way. Order was not necessary in what you learned earlier in this chapter. Here they are.

Think of what you do when you sit down at your computer in the morning, with it turned off. There are certain steps you take. First, you turn it on. Wait, maybe you plug it in (you did not want it left on because the glow of indicator lights keep you awake at night). Then you turn it on. Wait for the desktop to come up. Call up your applications you want open.

What you do may be different, but you get the idea. If you had to capture requirements for this, you need to break it down initially like this.

Now, consider a more realistic example. Here is the order that must be followed for an employee using a healthcare benefits system:

1. Add employee to benefits system

2. Employee enrolls into benefits system

3. Employee pays employee portion of benefits system

4. Enter employee transactions into benefits system

5. Benefits system pays employee for appropriate amount

6. Reports generated benefits system

You could draft the requirements as follows:

• 6-19 DRAFT The BOSS healthcare function shall allow an employee to be added to the benefits system.

• 6-20 DRAFT The BOSS healthcare function shall allow employees to enroll in the benefits system.

• 6-21 DRAFT The BOSS healthcare function shall allow employee to pay for the benefits.

• 6-22 DRAFT The BOSS healthcare function shall allow employee transactions to be entered into the benefits system.

• 6-23 DRAFT The BOSS healthcare function shall allow the benefits system to pay employees for the appropriate amount.

• 6-24 DRAFT The BOSS healthcare function shall allow reports to be generated from the benefits system

What is lost is that each requirement 6-19 through 6-24 must have the requirement previous to it done before it can be accomplished. You cannot enroll in benefits packages if you do not have access to the system.

How do you handle this in a requirement? You follow the process similar to in Chapter 4 where you write one requirement.

• 6-25 The BOSS healthcare function shall be executed in the following order:

  1. Add employee to benefits system

  2. Employee enrolls into benefits system

  3. Employee pays employee portion of benefits system

  4. Enter employee transactions into benefits system

  5. Benefits system pays employee for appropriate amount

  6. Reports generated from the benefits system

Notice that the requirement specifically states in the shall statement “executed in the following order” to indicate that order is important.

Please notice that this requirement is at a high level, and given the need for atomic requirements, this may not be at the correct level. That said, this requirement might still be necessary for a particular application to capture the order. There would be subsequent requirements for each of the six numbered items in requirement 6-25. It is likely, in fact, that each one of those six could have ordered steps within them. This means that there would be parent-child relationships between these requirements.

For example, let’s take item 2 and decompose it further.

• 6-26 The BOSS Enroll Employee to Healthcare Benefits function shall be executed in the following order:

  1. Select a Medical Plan

  2. Select a Dental Plan

  3. Select a Vision Plan

  4. Select a Life Insurance Plan

  5. Select a Short-Term Disability Plan

  6. Select a Long-Term Disability Plan

You may ask why this is a required order? We needed an example, and in this case, the insurance provider required it this way.

Order of Data Elements in Requirements

Earlier in this chapter, we talked about the listing of data elements . Do you need to order data elements, just like you did when listing? Good question. The answer is no. Some people might argue that. For example, do you enter addresses like this?

• Apartment number

• Zip code

• Street number

• City

• Street number

• State

Of course not. Then, you, gentle reader, say that you should specify an order. However, theory says it is not required to be in a specific order. Of course, you should present the data to the user in the order of terms users are accustomed to seeing them. Then, the answer is that the order is specified in the user interface. That is for a later chapter.

Of course, it makes sense to define the fields in the database schema in that same order. Requirements theorists agree with that. So, then why not say the order of the fields should be specified in requirements? If you remember from requirements definition rules, you do not specify implementation. Specifying the order of data fields in a table or database is just that—design how, not what.

The key element that you need to answer is the question, “Is there something in the order of the fields that is absolutely important to what the user must do?”

Exercises