Requirements - level of detail.

How detailed should requirements be? Should requirements always have the same level of detail?
That is a question which popups in nearly every requirements project. The only right answer i.m.h.o. is: It depends.

terminology
Before we proceed, allow me to spend some words on context and terminology. In this post I use the term "level of detail". There are other terms around, one of them is "granularity".

Context and domain
It is always important to establish the context of a discussion. Some methods distinguish between Business requirements and Functional Requirements. Some methods stress integration and traceability over all requirements. Without choosing sides in this discussion, I believe that much of what is written here applies to both. I do limit my scope to requirements for IT systems. Though requirements are also used in many other branches of engineering, my knowledge of other domains is too limited to say much useful about those domains.

Why would we limit ourselves?
Why would we not simply write out all requirements to the last detail? There are many reasons for this.
- Writing down requirements takes time. Time-to-market may no longer be as hot a topic as a couple of years ago, it is still often essential.
- Writing down requirements takes time, and time is money. That's no proble if it's your own money, but often someone else pays the bill, either your employer or the customer.
- Written requirements must be maintained. The application will probably exists longer than your assignment to the project, and any changes also may need to be a change in the requirements document.
- longer initiation phases means longer projects, and thus a greater chance that a changing environment will require a changed set of requirements.
Having said that, there are also very good arguments to DO write out detailed requirements:
- the need to maintain the application later may be facilitated by a good set of requirements. Though all too often I have seen outdated requirements, as programs always get updated, its documentation more rarely, its designs less rarely, and lets not speak about the rest.
- the need to ensure that no features are forgotten.
Many of the arguments in this discussion overlap with the arguments between agile and waterfall development.

Let's first have a look at some standard detail levels of requirements, and then have a look at this question in more detail.

3 levels model
A "high level" requirement has the form "Actor-Verb-Entity". Example: The system must show the account profiles.
A "standard" requirement has the form "Actor-Verb-Entity-Condition". Example: The system shows the account profile if the user is logged in.
A "detailed" requirement may still have "Actor-Verb-Entity-Condition" as above, or have "Actor-Verb-Entity-Attributes-Condition". Example: The system will show the user's own account profile, consisting of name-location, credit card info, recent failed login attempts, and recent ip-addresses logged in from.

However, other details may also be added, such as a calculation to be made, or screen details.

Cloud to clam
Other definitions are also used (Cockburn):
Cloud Level – very high level summary
Kite level – summary
Sea level – “single sitting” task descriptions
Fish level – small tasks that add up to valuable tasks
Clam level – very small details that make up small tasks
Cockburn uses these level when talking about Use Cases, but they may also be applied to other forms of requirements elicitation.


Now let's get back to our question: Should requirements always have the same level of detail?
As stated at the introduction, the level of detail depends. One thing it depends on, is its purpose. Requirements for which purpose?
a) For making a Function Point Analysis
b) For making a GO-NO GO decision of a waterfall project.
c) For making an INCLUDE / DON'T INCLUDE decision in an agile / scrum project on the next sprint.
d) For receiving a fixed date fixed price fixed scope (FDFPFS) tenders from suppliers.
e) For a system that you will build yourself.

These are quite different goals, and each has its own necessities. If the purpose is to enable an FPA: the decision here will depend on the level of the FPA. These in turn can be global, intermediate or detailed. These levels do not correspond 1:1 with the requirements levels described above.

Decisions for waterfall projects traditionally suffer from an overload of detail. Just because it will take long to realize them, and because managers are afraid for costly changes, managers and architects involved will feel uncertain and demand lots of details - even when the decision is just a GO / NO GO. This applies even more if the project will be realized by an external party.

For scrum projects, the main point is that any architectural risks and issues must be clear at the start. In RUP projects, architectural risks should be addressed in the first one or first two iterations. An important question here is: Are your requirements detailed enough to identify the architectural issues?.

FDFPFS projects typically require every detail to be spelled out, especially if a government agency is doing the tender.

If you intend to develop a system yourself, you may wish to sum up a feature list, in order to have a more complete mental image of what you what you are going to develop. A normal mind can mentally juggle 7 plus or minus 2 items, and your application may have more features than these, and more than you realized when you came up with the idea. Thus a feature list, or a use case model, may help yourself to get a more complete picture of the task ahead of you.

Requirements for whom?
You don't write requirements for the sake of writing requirements. Neither are you writing because someone pays you to write. For whom are you writing?
Let's have a look at possible answers:
a) For the development team: Nice, but what about this team? Do they know the subject area? If they do, you don't have to spell out every keyword in the domain. For example, if the team is experienced in the stock exchange, you wont have to describe call and put options.
b) For the CEO: IF the CEO doubts your knowledge and understanding of his business, you may be tempted to include more detail to show you understand his business. However, I find it very doubtful if the requirements document to be the document to convince him/her. Did you ask him what he wants to know?
c) For the testers: They want sufficient input for their test plans. But what input do they want for their activities? If they want to use your requirements as input for their global test plan, they might be satisfied with a feature list and a list of the non functional requirements. If they skip writing test plans, and just want to write extensive lists of testcases, they might require you to write up every last design detail. (And that they require you to do this, does not mean that you have to give in to them and cross the fuzzy line between requirements and design). Did you talk with them?

Requirements about what?
What is the topic you write about? If it is a highly technical piece of middle-ware, you may wish to concern yourself with the exact interfaces to be used. If this middle-ware is to be used by potential customers, you may be free to define the interfaces yourself. If at the rear of the application you have to connect to other components, some interfaces may already be given and non-negotiable, and have to be taken into account.
A traditional question here is: Am I talking about "what" or "how"?, though these terms are by no means a conclusive answer.

In which environment?
Did you have a look at your environment? And, no, I don't mean green. It may be that the organization has standards which have to be adhered to. Those standards have two sides, as given by these two questions: Did you list them as necessary for the project? Did you read them and found that certain non functional requirements have already been taken care of?

Another environment issue is the development tooling. Though the temptation to include solution specific terms might be great ("we all know it will be a website based on server based java"), this temptation should be strictly avoided. Nu terms like "persistence unit", or "sql table" should be used in a requirements document.

One last question: Do all your requirements have the same level of detail? I hope NOT. It is perfectly valid to work out some requirements to a very detailed level, while having others kept at a global level. For example, adding and changing an employees salary component may be standard, and described in five words. A salary calculation may take you several pages of detailed formula's.

graph theory


If we represent the relations between requirements as a (directed) tree (in the sense of graph theory), the vertices should represent the same level of abstraction. In other words, the degree of the vertices of degree 2 should have about the same level of abstraction.
But the leaves need not all have same degree, that is, the same distance between root and leave.

Links
iag
tyner blain

Configuration Management Plan

In ASL, Configuration Management is one of the five processes in the Maintenance process cluster. Like all processes, we want everything we do about it to be clear, structured, managed and audit-able.

The ASL-Bisl foundation, which you can find here, inherited all the stuff from the ASL foundation. It has a "Configuration management plan maintenance" and an example.

Unfortunately the plan does not state the goal of the document. Why is the CMP written?

In my humble opinion, a configuration management plan fits into the Waste - definition of Lean. Still, it is a useful item to prevent other kinds of waste.

A good Configuration Management Plan fits into both Maintenance and Development.
The configuration Management Plan defines  the items that are governed by the CMP, and the processes governing these items.

The CMP thus makes everybody involved clear:
A - what items are important to us?
B - where are these items stocked?
C - what is their status?
D - how do we make sure the items and their status is up to date?
All the rest is bogus.

Now why is this Waste as defined by Lean? Simply because it is not a primary process to produce what the customer demands of an IT organization. Is it useful? Yes, nevertheless it can be very useful, because it prevents other wastes.

These other wastes include:
(i) - Having lost track of items which are important nevertheless. On of my customers, an organisation with a large IT-department, had programs running. These programs ran for years, and never got changed. When after some 10 years they had to be changed, the sources could, albeit with considerable effort, still be hunt down, but the development environment was lost, simply because no one knew it was important. So it is very important to make a list of ITEMS which are important to a project or organisation.

(ii) - In the previous example, I used the expression 'hunted down' on purpose. Looking for programs can be extremely effort costly, even with networks and search facilities available. This search effort is clearly a waste of time. Thus: For every item you deem important, write down WHERE

(iii) - Did it ever happen to you that the developer made three copies of the programs - just to be sure? Fine. Now which is the current version? Time to sort this out is waste is Lean terminology. That is why it is important to keep track of the STATUS.
Status will generally vary over time. With version 2.2 in production, version 2.3 may be in acceptance test, release 2.4 in development and release 3.0 on the drawing board. Unless you know which status each items has, you may have a problem by moving a wrong component into production.
Another pitfall is the release that was successfully developed, but which did not move to production because of other business concerns by the customer. After three years, no one remembers this stalled project and items from the most recent version may be used for an emergency production patch - with all disastrous consequences, because software suddenly fails as the item moved depends on other items changed in that release.

(iv) It is one thing to write a CMP once. It is quite another to stick to it. Therefore the processes to change items and to maintain the CMP must be described too, and be part of the CMP. The processes described in the CMP govern Items, the Storage, the Status and even the CMP itself.