functional requirements - use wording based on verbs?

Question

Question

Should the functional requirements in a requirements doc use wording based on verbs?

Context

School assignment, working in a team, working through the SDLC. The requirements doc has been done and we are now into design.

Problem

The requirements doc has an enumerated list of what I'd call features of the app - the functional requirements. In that list are things that I'd think of as "how's" rather than "what's" and now, trying to work on design, I feel like a part of design has been prematurely dictated.

I've not done this before! To me, I should be dealing strictly with things that describe "what."

Example of current

Pretend that the job is to make an omelet. Listing: crack the egg, break into bowl, scramble, etc.; crosses over the line into the territory of how. Along that track, so does wording like: create, generate, list, calculate, determine, validate, etc. - verbs, basically. Right now, I have a list of requirements that are partially rooted in verbs.

My idea of a requirements doc for an omelet would be more like: has two eggs, x ounces of ham, x ounces of bacon, x ounces of montery-jack cheese, x ounces of cilantro, etc.—nothing but what (nouns).

I might have, and could have, spoken up before finalizing the requirements doc if I'd had any experience.

Answer 1

You can and should use verbs in your requirements. The important thing is to make sure each requirement is:

• Unambiguous - each requirement can only mean one thing and can only be interpreted one way.
• Atomic - each requirement cannot be broken down into multiple requirements.
• Testable - each requirement can be shown to have been met or not met via some form of testing.

You'd be surprised how good your requirements turn out by just following these three guidelines at all costs.

Also, be sure to write a rationale for each requirement. This is very important and useful down the road when someone wonders why a particular requirement was created.

And yes, you are correct, the requirements should describe WHAT the software will do, not HOW it will do it.

Answer 2

"Should the functional requirements in a requirements doc use wording based on verbs?"

The short answer is "yes", but the path to get there is winding.

If the requirements doc is a collection of "shall" statements written as English sentences, you must have a verb phrase. And that verb phrase will the "shall xxx" as in "the system shall xxx". The "xxx" part is one of three types of verbs, "be", "do" and "have". These sentences must describe the system as a black box, only recording those things that can be seen from the outside. As you said, "the what rather than the how". If it is visible from the outside it is a "what".

The only possible function that is available to a digital system is to change the value of a variable. Therefore, all functional requirements must state what variable is changed and the calculations that are used to do the changing. These are the "do" requirements.

The "be" requirements tend to describe features rather than functions. "The system shall be able to ...". They describe a "state of being".

The "have" requirements are the nouns that you talked about. "The system shall have ..." They provide the nouns for the functional requirements sentences.

At a high level there are very few functional requirements. Most of the requirements are either feature requirements, performance requirements or compositional (have) requirements.

All high level requirements that need children are, by definition, ambiguous. If they were unambiguous they would not need children to define them. Further, a requirement is only unambiguous if the majority of the people in a requirements review declare that it is. I.e, ambiguity is subjective. The closest definition for an unambiguous FUNCTIONAL requirement that I know of is at BarBaraBea.com on the "Unambiguous Functional Requirements" page. Basically is says that all of the nouns in a functional requirement must be derived from the system inputs through a chain of unambiguous functional requirements, and that the statement of the computation in the requirement must describe an algorithm. The definition of "algorithm" is much less subjective than the definition of "unambiguous requirement".

Answer 3

...Pretend that the job is to make an omelet. Listing: crack the egg, break into bowl, scramble, etc.; crosses over the line into the territory of how...
...
My idea of a requirements doc for an omelet would be more like: has two eggs, x ounces of ham, x ounces of bacon, x ounces of montery-jack cheese, x ounces of cilantro, etc. - nothing but what (nouns)...

Well for omelet, I would prefer first version requirements to second one, simply because second version puts me at risk of getting two eggs, x ounces of ham, etc - nothing but that, neither fried nor scrambled.

Second version guarantees getting what I need, but it somewhat sucks, too - just because the only way to make sure that requirements are met seem to be to stay in the kitchen closely watching each and every step of making a meal.

You see, I would prefer requirements that would somehow allow me to test / verify the result without being forced to watching how you prepare the meal.

One way to achieve that would be to specify requirements as passing comparison against reference. Using omelet example, I would make my own "reference" omelet following same instructions as you, then compare yours for being close enough to it.

• ^{I used that approach when I needed to test a heavily optimized version of particular algorithm. "Reference omelet" in this case was presented by simplified, non optimized algorithm. I run the same input with two kinds of algorithm then checked if output produced by optimized version was close enough to the reference.}

Another way would be to state requirements so that these describe result. For omelet that would be like "4 oz of eggs, scrambled and fried, etc...". I dealt mostly with this kind of requirements - I think this is most typical way.

• ^{For the sake of completeness, I probably have to describe yet another kind of specifying requirements I have dealt with - test-based. I can't imagine a way that wouldn't sound lame for omelet example - something like "when expert looks at and tastes it, they say OK" - but have to admit, in the only case I've seen it used for software, it didn't feel particularly smart either.}

Answer 4

A functional program is composed of functions. What are functions? They are methods that perform actions. What are action words? Verbs.

If you were doing object oriented programming, then you would be working with nouns. Actually, you would be working with both nouns and verbs.

Functional style:

crack(egg)

Object-oriented style:

egg.Crack();

At the requirements level, I'm not sure that any of this matters, although it would certainly be helpful if the requirements were stated in the form of actions, since functions are what you will be writing.

Answer 5

All requirements can essentially be reduced to a collection of statements that revolve around the use of verbs. Yes, you can throw in a few nouns and adjectives, but it's the verbs that describe how a system behaves, and what it is that the customer wants the software to do. Even a lot of the state-specific functionality of a program can be thought of in terms of behaviours when you present state through getter and setter methods.

It's just like CFL_Jeff mentions in his answer, that you want to have your requirements describing what a system will do, and not to describe how it should be done. This is possibly why I find the behaviour-driven development so compelling, because it encourages the use of verbs do describe requirements, and the use of verbs when writing unit tests to describe requirements as behaviours to be tested.

Consider for a moment the following requirements and scenario templates:

• As an {actor} I want to {do something} in order to {achieve an outcome}
• Given {an initial context} When {something is done} Then {expect an outcome}

In BDD, features are always the bit described in the "I want" section of the template, and they are always loaded with verbs describing what the feature does. When testing, a Given-When-Then template is used to validate specific scenarios pertaining to the feature, and once again the "When" section of the template is always defined by the verbs used, which relate back in some manner to the verbs used in the feature specification.

Using your omelete example, defining a number of behaviours as a series makes a lot of sense. You have a collection of behaviours, and outcomes, and as a series they form a workflow. If you were to instead define a list of ingredients, you are effectively describing the architecture very loosely, however you are left with a lot of questions. What is the workflow? How are the ingredients to be used? You are basically missing the "glue" that will guide your decisions about how to put your system together, and how your system is supposed to behave.

By defining requirements in terms of behaviours and outcomes, you are able to provide a very clear picture of what it is you want the software to achieve, without worrying about how to specifically achieve such outcomes in software.