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.

U/A/T: there's some homework for me! It is reassuring to get confirmation that WHAT is the goal. Showing rationale might need some work. Thank you.
–
yasMar 26 '12 at 21:01

P.S. - thanks for recognizing the general concept and context rather than focusing on the "omelet" scenario which was just offered to simplify, provide something concrete, and not expose details; it was off the top of my head; impromptu, really.
–
yasMar 26 '12 at 21:48

@yas No problem, good on you for making the effort to improve the requirements after you realized they were too designy!
–
CFL_JeffMar 27 '12 at 12:30

It's normal to have higher and lower level requirements where the higher ones are broken down to lower ones - in a project involving design rather than just coding I would expect a tree of requirements not just the lowest level atomic ones.
–
Pete KirkhamJan 30 '13 at 22:47

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

I'm actually quite in line with this answer. We were even using the following pattern to express functionnal requirements (and this pattern helps a lot): A given system shall (do, create, boil...) something, in given condition, with said performances.
–
Marc-Emmanuel Coupvent des GraJan 29 '13 at 23:33

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

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.

Did not expect that answer; we never discussed Functional vs. Object styles. The given language is Java and I/we(?) presumed Object style. It seems that leaving out Java as the language was an oversight on my part. Your answer gives me some insight I did not expect! Thanks for the reply.
–
yasMar 26 '12 at 20:21

Functional requirements of a system are not to do with whether its software components are implemented in a functional programming style, but are those requirements that govern flow or transformation of matter, energy or information (see Pahl and Beitz's 1988 'Engineering Design', John Gero’s Function-Behaviour-Structure model of design, or numerous other engineering requirements or design papers and books).
–
Pete KirkhamJan 30 '13 at 23:00

@PeteKirkham: I didn't make that assertion.
–
Robert HarveyJan 30 '13 at 23:01

So why are you talking about functional programming at all?
–
Pete KirkhamJan 30 '13 at 23:09

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.

Currently one of the software products at work is failing as it uses too much CPU for the splash-proof case the system it runs on to dissipate the heat. Although you can define some such requirements as verbs - 'the portable monitoring system shall come in an enclosure which meets IP 4 water ingress standards' - it seems the only verb is 'come' and no behaviour of the component which is causing a risk that the requirement will fail to be satisfied is present in the customer's requirement.
–
Pete KirkhamJan 30 '13 at 23:08

@PeteKirkham You've described a hardware issue. Specifically a specification of form, not of function. This does not invalidate my answer to the OP's question which is about functional specification. Addressing the case you have described however, your functional specification might be "Given 'Software Configuration X', When CPU usage exceeds (a pre-specified limitation & time), Then Expect System Failure". Better yet, replace "system failure" with a "recovery process" to specify how to avoid failure. Sometimes we need to think a little creatively in order to uncover specific behaviours. :-)
–
S.RobinsFeb 7 '13 at 13:27