Writing Atomic Functional Requirements

Type: Principles and Rules
Sources: my work in the late 1990s with Sven Biedermann; the SOPHISTs; Dan Berry's Ambiguity Handbook; a discussion on shall vs must in requirements on Tyner Blain; Alistair Cockburn: Agile Software Development (his words about communication bandwidth, taken from here); Capers Jones: Estimating Software Costs, ISBN-13: 978-0071483001
Todo: use Tyner Blain taxonomy; look into Toms functional requirements (binary?)

Ambition

explain how to write atomic functional system requirements so that the spec is easy to read, and ambiguity is kept to a minimum.
Local definitions:
atomic: cannot decomposed further. 'Note that it is not always necessary to write these kind of requirements down
functional: describing WHAT the system has to do 'not HOW WELL it has to perform

Note that we are NOT TALKING about the even more important (non-)functional user requirements here, in a sense of what a stakeholder expects from the system, which problems shall be solved, what shall be the inherent qualities of the solution etc. I do not intend to argue that any spec must include atomic, functional requirements. But sometimes setup is so that it must. Don't forget to establish the context first.

Gist

A major shortcoming of system specs that are written in normal present tense („The User edits DateX“) and free or narrative form is their possible ambiguity. While natural language can almost always be interpreted in various ways, authors of system specs should do what they can to minimize that effect. Two defects are most common in specs that use a free form:

  • Nominalization, i.e. a verb is transformed into a noun, normally eliminating important information like 'who' and 'when'. Most nominalizations distort processes into events.
  • Generalization, i.e. details which further specify a process, or object or subject are omitted.

The rules presented here help avoiding both these defects.
At the same time, due to the uniform sentence structures, the reader can read much faster (guesstimate: at least 4 times faster) AND has less trouble comprehending the text. In fact, even untrained readers can employ some kind of speed reading to such a spec, because the meaningful content is much easier to decipher.
In order to see the advantages you should observe and understand three specification principles.

Principles

P1: Written once, read many times

Specifications of an IT system (like other texts), are written once, and are read many times over the lifespan of the system. Hence two observations become clear: reading time matters more than writing time, and upfront quality is free. I.e. it makes sense to optimize the text for readability and comprehensibility, even if that means the author has to put in more effort.

P2: No Nobel prize in literature

Specifications are technical texts written for one purpose only: the successful transfer of meaning from one person to another, over distance and time. The author will never win a Nobel prize in literature for it. Therefore it does not make sense to put effort in an aestethic, pleasurable text.

P3: Specifications are for systems

System specifications describe what is required from the system. This should not at all prevent you from describing what the users do (in the sense of a business process desciption), but you want to do that in other parts of the documentation (use cases, for instance).

P4: Detailed written documention has very low communication effectiveness.

Therefore writing detailed functional requirements might not be the best of ideas. Consider NOT doing it if you expect a high rate of requirements creep. Assume a change rate of 2-3% per month if you do not know the specific change rate of your project (which actually IS high, though widely experienced).

Rules

R1: If you want to describe an action that has to be performed by the system alone, use …

Autonomuous system action requirement :== The system <must|should|can> <verb> <object(s)>[, <if|as soon as> <all of|exactly one of|at least one of> the following conditions are true: <condition1>[, <condition2>]*]>

Notes:
System action requirements define the solution space from the inside, i.e. they describe the area of valid solutions in positive terms.
You indicate priority and/or obligation by choosing the respective auxiliary verb.
You need to clearly define your strong verbs in a glossary. Usually you end up with 10-20 verbs you need throughout the spec.
logical conditions should be indicated by the keyword 'if', time conditions by 'as soon as'. Avoid 'when', because it is ambiguous.
Conditions, especially if there are many, should be put at the end of the requirement, to establish a context first. Only if there's a single, simple condition you can put it in front of the action.
If there are complex conditions, do not hesitate to use some form of logical expressions. Just make sure you explain their use in the requirements management plan.

R2: If you want to describe a capability the system has to provide for some user, use …

User interaction requirement :== The system <must|should|can> provide <whom> the capabilty to <verb> <object(s)>[, <if|as soon as> <all of|exactly one of|at least one of> the following condition(s) are true: <condition1>[, <condition2>]*]

Notes:
See notes of R1.
Interaction requirements too define the solution space from the inside, i.e. they describe the area of valid solutions in positive terms.
It's not valid to avoid the passive voice by making the object the subject in the above sentence structure (e.g. „The user must do X“), because the spec must describe what is required from the system, not from the user. Ask your company's lawyer if in doubt.

R3: If you want to describe a constraint, something the system mustn't do or allow, use …

Constraint requirement :== The system mustn't [<allow whom> to] <verb> [<object(s)>]

Notes:
Constraint requirements limit solution space from the outside, i. e. they describe the area of valid solutions in negative terms.
This negative character makes constrains hard to test, as you cannot see the absence of things in a system. In essence, you check whether the constraint (for example a legal constraint) is violated by the system or can be vialoted by a user using the system.

R4: If R1 – R3 do not fit your needs in writing atomic functional requirements, change them.

Note: While the above sentence structures emerged from a number of projects successfully done and thousands of requirements written, your situation might be somewhat different. Change the rules. One idea is to not write atomic functional requirements in the first place, and opt for use cases and detailed acceptance criteria.

Related Pages

Where to go from here? Link other pages in bullet list.

rating: 0+x

If you want to know more about a topic, simply tag the article with a 'morePlease' or 'examplesPlease' tag!

BlinkListblogmarksdel.icio.usdiggFarkfeedmelinksFurlLinkaGoGoNewsVineNetvouzRedditYahooMyWebFacebook

Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License