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.

agile requirements : lessons from 5 unusual sources

Just a short remark this post: the magazine Agile record has a nice article by Raja Bavani on requirements lessons from 5 unusual sources.

From observing restaurants and waiters, he learned:

1. Welcome customers and stakeholders with a smile whenever
you interact – even when you are on the phone
2. Listen well to understand the requirements
3. Rephrase or summarize your understanding to get confirmation
before you end a conference call or a meeting
4. Believe in your expertise and stay committed
5. Be flexible enough to re-prioritize and accommodate
changes as long as it is not too late
6. When it is too late, be polite and communicate the impact
7. Be open and ask for intermediate feedback during your interactions
8. Feel free to talk about ‘what else’
9. Value time and money
10. Apologize when things go wrong

He emphasizes no 3: rephrase or summarize each requirement to check if you understand it well. Though rephrasing every requirements may be overkill, imho it certainly pays to do this for every requirement that might be unclear or liable for misinterpretation. And of course no 1 is a great way to keep spirits up. In my current project their is one colleague that manages to find something fault with everything. Everything is useless. It is very tiring to work under such circumstances. Keep up a smile, and look for possibilities.

From observing airports and flights he learns:

1. Preparation is critical to success. This is applicable to the entire agile team, including product managers or product owners, agile project managers or scrum masters and agile teams.
2. If you arrive late, you miss the flight. In the same way, you can’t accommodate late arrival of requirements during iterations.
3. Any delays or changes can only lead to further delays.
4. Change management can never be effective when there is no support from all stakeholders. You cannot blame an individual or a small group of individuals when things go wrong because of ineffective change management.
5. Dependency management in large projects is necessary to avoid wait time and delays. In case of large projects with many related projects, we need a function or a team that plays a role similar to that of the control tower in airports. In most cases, we call it the governance team.

His third source are children. Children are curious and explore without inhibition, he says. Though I disagree with the latter, I'd like to stress the positive effects of curiosity. In my youth in native Netherlands, curiousity traditionally was not encouraged in children. Some old proverbs as an illustration: Children who ask are skipped over, children may eat everything but not know everything, a curious ann (een nieuwsgierig aagje), and do on. But curiousity is the engine of discovery.

Likewise, he learns the importance of communication skills from schools and teachers.

His last lesson comes from ant colonies. I'm not very convinced about what he writes here, so i'll skip this topic, though what he writes about team roles is true.

You can find the complete pdf here. Certainly worth a read!

Requirements - functional perspective, structural perspective, behavioural perspective

IREB, the International Requirements Engineering Board, makes a distinction between three types of modeling perspectives:

• Structural perspective
• Functional perspective
• Behavioral perspective

Each of these views can be modeled in a view, which are aptly named:
* Structural view
* Functional view
* Behavioral view

At first sight the latter of the two may look as overlapping. Let's have a look at these three perspectives.

The structural perspective concerns itself with the structure of the elements which make up the system.
In UML it is supported by the following types of diagrams:
* class diagram
* component diagram
* composite structure diagram

For the functional perspective, typical UML diagrams are:
* Activity diagram
* Use Case diagram

For the behavioral perspective, i think a typical UML diagrams is:
* machine state diagram


In the above text I used the word 'modelling'. I know that this word is sensitive, as some requirements specifiers maintain that modelling is part of design, not of requirements elicitation. That discussion is quite another topic, and I only used the word because the IREB uses it in this context.

Dare to ask / durf te vragen

Dare to Ask is the English translation of the Dutch eBook "Durf te vragen", written by Niels Roemen and Fanny Koerts. "Durf te vragen" has grown into a popular tag on Twitter, but is not yet well known in the English language world. This post contains a short outline. Should this outline generate a lot of interest, I'll see if I can find some time to translate parts of the ebook into English.

Introduction
"Dare to ask" was invented some years ago by Herman Drummer and Nils Roemen. In no time a couple of "dare to ask" sessions were organized. The sessions grew in numbers. So did the number of session coaches. By now #durftevragen is a well known tag on Twitter.

Dare To Ask is founded on the principle that everybody has a social surplus: knowledge, ideas or skills that no one else has, and that somebody else needs. Many people like to help for free.
In 2008, 50,000 volunteers cleaned the entire country of Estonia. It took them 5 hours.

People often hesitate to ask for help: if you as for help, you may appear to be weak. We like to solve our own problems. We are afraid that others will ask something in return. The latter rarely happens.

By not asking we deprive others of the opportunity to help. Asking offers others the opportunity to share their social surplus with us.

1) What's going on?
Sharing has never been easier. While knowledge monopolies meant power, now the ability to share knowledge has became a powerful pillar of innovation. TED is an initiative to share ideas. When other places wanted to organize similar sessions, the initiators decided that sharing the concept of TED would have greater impact than a centralized TED monopoly. Universities often put their colleges on line as videos. Wikipedia is according to one research as reliable as the Encyclopedia Brittanica. Wikipedia is written by volunteers sharing their knowledge. Open source software is a very successful kind of software.

We should realize that all of us have more ideas than we can realize. So giving away the ideas we can not use ourselves might be a good idea. Social media such as twitter and Facebook are great ways to share ideas and knowledge. But we should not forget RL (real Life), it is a human necessity to meet eye-to-eye, and a very effective way.

Everybody may become an expert. In his book Why Some People Succeed and Some Don't Malcolm Gladwell shows that everybody can become an expert at something - but it takes some 10.000 hours of hard working.

2) What do you want?
Successful therapist Jan Willem Wolff asks his clients: Who really wants what? The 'who' and 'what' are important items in the failure or success of a project. The must be a person who really wants something, and he must be able to express that in a very clear way.

If you don't have the determination to make your dreams and ideas come true, why would other help you? Define your ideas and goals, and communicate them. If you don't communicate them, others wont understand them. And if they don't understand them, and understand why they are important for you, they will rather invest time in their own ideas than help you.

Real dreams are often bigger than the possibilities and skills you have available at the moment. So don't be shy to ask for assistance. Still people are often afraid to ask.

Three misconceptions:
1. maybe they'll ask something in return. Yes, there is something like a social bank account. Someone who helped you may ask you for something else. Help the other when you can, but not above that. And you can ignore people who only ask and never give.
2. Asking for help is a sign of weakness. Yes, but the ancient Greek already knew: the more you know, the more you realize that you know very little. It is no sign of weakness to admit that.
3. Stay in control. Yes, if you delegate some things will go wrong. But you have more talents available when you use those of others instead of just your own.

3) What is a good question?
A good question is a question that gives useable answers. That need not be a shorty question. It may be a short story. Try to describe the stories and images in your head. Chances are that others will add details and parts. Talk to people, preferably with people with another mindset. Exercise asking your questions to different people. Watch when people are 'turned on', when they start to think with you. 'How' questions are often good questions to make people start thinking

If your questions don't generate answers, in a 'date to ask' session, or on twitter, it may have different causes. Maybe people have no ideas. It may be a topic they know little about. Maybe they feel guilty for not being able to help. Maybe you will have to alter your question. Maybe you should ask others.

4) Who wants to help me?
It's a waste to leave the capacities of all those people who are waiting outside to help you, unused. In the strength of weak ties, sociologist Mark Granovetter argued that distant acquaintances may have the capacities most needed by you, because your close friends may have similar ideas to you.

Some people drain energy from you. Others give you energy. Find the latter.

But if, after a few hopeful ideas, real obstacles are mentioned, give them serious thought. It's no use to work on something impossible.

5) Hands on
Sometimes people invest a lot of time and effort to ask all the right questions, to mobilize people, and and to collect good answers. And then they do nothing with them!

This is not surprising. Knowing what to do make you also realize how much more time and effort is required to attain your goal.

But you may also create your own failures by looking up against all the effort, or by looking back at previous failures. Instead, try to look on the rewards of success. On the target that you set yourself. Think in terms of possibilities (at the same time, do give problems serious thought: what can you do to overcome them?)

Don't keep things secret. When someone started selling t-shirts with #durftevragen, our first reaction was shock. We contacted the seller, who responded very honest. Now every sold t-shirt is one more sales person walking around without any effort on our side.

Start doing something with your ideas. You don't always need an business case, filled in tax forms, a webdesign, a logo and a business plan. You do need to start putting your ideas into reality: making them work.

Dare to fail: Maybe you are afraid starting to put your ideas into action because you may fail. Yes, this is scary. Yes, you may fail. Risks are necessary in this life. Yes, failing hurts. But not trying to put your ideas into action means failure anyway. Where do you want to fail? Do you want a chance on success?

Open source software such as Apache is among the most popular software in the world. Sharing is powerful. Of course some villains may steal ideas. No longer share with them, share with others. But keep sharing ideas which you are not gonna use anyway. Steve Johnson, in Where Good ideas come from, showed that good ideas often stem from interaction of ideas from different people.

Value determination after usage: within DurfTeVragen/DareToAsk we decided to work on the base of value determination by the customer. After a session, the customer may decide what the session was worth for him.

7) The toolkit
Over the years the DareToAsk coaches discovered what increases the chances that you get what you ask. Think Have courage Do random acts of kindness (randomactsofkindness.org) Believe it is possible Look at people as persons, not as trades Associate with heroes Do what makes your heart jump Challenge others to do what makes their heart jump Measure your happiness. make sure you have a safetynet Be kind Choose Yes instead of No Choose what makes you glad, not what people expect from you Help strangers. What do you notice? Without practical steps you don't get anywhere

Open space meeting technique

Yesterday evening I visited a nice meeting of nl-scrum. I had no scrum experience, though I do have a long standing interest in "light weight methods". The topic was user involvement. User involvement in scrum is organized through the presence of a Product Owner, who withing scrum has his / her own set of challenges. It was nice to hear some Product Owners speak about their experiences.

Contrary to most meetings, presentations were just a minor part of the evening. The main part of the evening was devoted to "Open space". A nice concept, which I really like. Te concept has been used for meetings with 5-2100 people. It seems the history of Open Space Technology is detailed in the Introduction to "Open Space Technology: A User's Guide", by Harrison Owen.

There is a wall where anyone can post a topic. This is sometimes called the "bulletin board". The "open space" is sometimes called the "marketplace", and has several places (for example labeled A, B, C and D).

Topics can be noted on the bulletin board using whiteboard markers, post-its or any other convenient way. Example:

A	B	C	D
Product feature: colour	Sales channel fb	Patents: now or later?	Legal harassment risk: look alike
No menpower for design	product feature: keyboard	wow factor?	org barriers

The topic initiator, also called a facilitator, is supposed to move to his corner of the open space. Anyone else chooses the topic he is most interested in.

Rules are: The first rule, Whoever comes is the right people, simply makes sure that everybody is welcome in any discussion. Nobody should be locked out of a discussion.
The second rule, Whenever it starts is the right time, acknowledges that you can not force a discussion to start. Discussions start only when people care about something.
The third rule, Whatever happens is the only thing that could have happened, is meant to have people concentrate on the AREs, not on the SHOULDS, COULDS or whatever.
The fourth rule, Wherever it happens is the right place, reminds us that it is not important where a discussion takes place. If it happens to be at the coffeemachine, fine. This rule is not mentioned by everybody.
The fifth rule, When it's over, it's over acknowledges that discussions are over when a consensus has been reached. It has no use to draw out a lengthy discussion for the sake of discussion. Discussions can not be planned, some will take more than one round. They can be re-planned on the bulletin board again for a new round.

Law of two feet:
- if you neither learn nor contribute from a discussion, move on.
The law of two feet makes sure that people feel free to move around. Find another breakout session, another discussion, make sure you use your time useful.

The discussions/breakout sessions are alternated with round ups, where all participants are standing or sitting, preferably in a circle, and topic initiators present the result of a discussion.

The literature mention two types of people:
Bumblebees fly from conversation to conversation, picking up ideas from one and insert them in others. Butterflies fly from discussion to discussion and pick up ideas for later exchange.
Except these 2 roles there are those of facilitator and participant.

The Open Space Meeting technology has been used in open source, engineering, legal, and many other environments. They make sure there is cross pollination between different discussion groups.

In the links below there are people who say that you can use the technique only or best when:
- conflict is present,
- things are complex,
- there is huge diversity of players
- the answer was needed yesterday
I'm not sure all of these conditions are needed. Yesterday there were no pressing problems, just a bunch of 20-30 interested people. No conflicts, hour we were a very diversified group.

Quote:
"The 2 days of Open Space that followed were a success, a miracle in the words of the CEO and he added that 3 years ago they received a thick report from ___ (a famous international strategic company meeting in Israel) that cost $1.5 milion, and they could implement a little. Now we produced something much better in the cost of 1 page of their report, and it seems that we can implement it all." – Avner Haramati

Links:
wikipedia
out of the jungle blog
just another site