How to Write a Requirement for CMPS 115

Different organizations have different rules for how to write a requirement and it can get real technical out there. For this class, a simplistic and retro approach is going to be taken. Here are the rules:

1. Each requirement is numbered.

2. Each requirement is one sentence long.

3. Each requirement is tagged as to whether it is defining, distinguishing or blue sky.

4. Each requirement begins with the phrase "When the user . . . "

5. After the user action is described, the visible, TESTABLE response of the system is described, starting with the phrase ". . . then the xxx shall . . . "

6. If the system does more than one visible thing in response to a user action, all the responses will be stated in a list form.

Examples, Good and Bad

Good:

7.1.2 Defining When the user invokes the help function, the Dots & Boxes game shall display a help file containing the game rules listed in SRD para x.x and describing the controls listed in SRD para x.x

Why this is good: It has a number and a tag. It states the user action, so you know it's something the user does (as opposed to the o/s, over which you have no control, or another part of your game). It states the system response - there's going to be some text displayed and it's going to contain the following info. You go to the referenced paragraphs to find out what's in the help file, rather than listing all the things here, so if it changes, you only have to change the list in one place.

Bad:

The Quit button is used to exit the system. When the quit button is invoked, the Interface software accesses the GUI and invokes the "Window Close" method.

Why this is bad: It doesn't say what the user does. It says that there will be a quit button - that ties you down to an implementation; what if you want to invoke it from a menu? Or by a right mouse click? Or from the keyboard? It doesn't say what the observable effect of the Quit button is - we don't know what the "Window Close" method does, so not only will we have to write test software to figure out if the "Window Close" method is actually invoked (because we are required to check that the method is invoked since it's in the requirements), we don't know if it actually causes the windows to close and the app to disappear. The requirement is not tagged as to it's importance, so we have to assume it's defining. It's not numbered, so when we're talking about it we have to say "You know, the requirement about quitting and closing the windows?"

Good:

7.2.3 Defining When the user invokes the Dots & Boxes game, then the game shall display the following

a. a game matrix consisting of an 8 x 8 grid of dots

b. a quit control

c. a restart control

d. a help control

e. a message stating that it is Player 1's turn

f. a score area with both scores set to 0.

Why it's good: It has a number and a tag. It states what the user does. It states what the software does in response. All the responses can be measured - in this case, for existence as well as for correctness - and checked off. The system had multiple responses to one user action, so all responses are listed and they can be referred to individually. That is, you can discuss Req 3.2.1.c as opposed to 3.2.1.a. It doesn't say what form the control will take: a menu, a button, a drop down box, a text box - you're free to modify your thinking as you know more.

Bad:

7.4.1 Distinguishing When the user invokes the Dots & Boxes game, and then the game shall display the appropriate controls.

Why it's bad: What's "appropriate"? The purpose of doing requirements is to set customer expectations so there are no surprises. Chances are, the customer's definition of "appropriate" is far different from yours. Sometimes people think they are being clever by avoiding a confrontation, but it's not usually clever. Deferred problems usually turn into more expensive problems because other design decisions get made based on false assumptions. If you don't know absolutely everything about a requirement, just write down as much as you know and flag it to revisit it. Ambiguity costs money and time.

There are always exceptions, though.

Notice that there are lots of words that could be argued about as ambiguous in the requirements I said were good - what does the "restart control" do? First, you should have a requirement that defines that. Second, you and your group and your customer will find some common language that doesn't have to be analyzed and defined in detail. If you can agree on language, it's very efficient to not have to define everything, and if you're working on a small enough project over a short enough length of time, it's absolutely the right thing to do to take advantage of the common vocabulary. You want to make this as simple as possible, but no simpler.