Archive for the ‘Requirements and specifications’ Category

I was listening to one of my favorite bloggers today, the podcast from Hanselman is about lean development and starts out about defining success. The first statement is that defining success for a software project to be “on time” and “on budget” is rather misleading. And then goes on to defining success as wether the project is a business success, that is a business case with a positive outcome.

I really like the podcast and it gave me an idea of another way to describe what I blogged about a few weeks ago in my post on UATs and my series on Requirement specification.

I tryed explaining the usual short comings of requirement specifications based on Change management theory, funnyly enough applying the metrics of succes that the above podcast is about would yield the same conclusion.

Usually the requirement specifications are very low level describing small steps needed to complete some function but generally that “some function” is not described at all. “Some function” in this context is a task that the end user needs to perform to complete everyday work.

If you wrongly define success as just being “on time” and “on budget” you might define a project as a success even though that project was such a lousy business case that the company went backroupt, you know that happens everyday. (Just talk to your manager, also know as the  #if the project is not a success we’ll go backroupt” management style)
Same goes for requirement specifications that have forgotten that the most important part is actually the tasks the users need to complete, not every single step on the way.
I’ve seeen numerous projects that met every single requirement but the user found them at best difficult to use. Defining them as a success even though they met all requirements goes against the logic of the users im sure.

I find a good way to measure the success is to “user metrics”. If the system is build to help users perform their tasks faster, then let’s measure how fast the users are when we start the project and how fast they have gotten when we’re done.
If the system is build to make our products easier to use than the competitors, let’s ask the users what they think in regards to usability and so on for the high level goals each project has.

If we start out every project by documenting these high level “user goals” we make it easier for us selfs to review requirements.

When you’ve read the requirements you should be able to do one of three things with each requirement

  • Relate them to a high level goal
  • Discard them
  • Create a new high level goal

When all requirements are related to a high level goal, look at every high level goal and ask your self and the project “do we have all the information we need to meet that high level goal” The answer is probably “no :-)”. At least I found my self time and time again needing information. To be honest I often find my self in that situation when i did not to as I “preach” in this post. If the answer is “no” I for one will in the future try and remember to go out get that information


In the first part I wrote about common pitfalls when creating requirements documents. In part 2 I tryed to give an example and describe the outcome should one fall into one or more of the pitfalls.

This final part is based on a speech, I had to give a few months ago. The goal of the speech was to get the listernes to value the points, I’ve written about in my series on Mr. Work, especially the points from The Story of Mr. Work and the Love for UATs

Basically I wanted the audience to experience some of the challenges, that developers and Architects face every day.

Instead of just giving a speech, I decided to take a chance (this was when I was preparring the speec h not some last minute decisions, which would not have work).
I asked one of the listerners (they were 6) to come to my white board and describe Bathroom of his dreams (you know you had dreams about bathrooms, so of cause he’d had them too). He was to describe it in the form of a bullet list.

He wrote stuff like: 2 sinks, a lot of light and spacious. Actually most of the bullets were rather detailed, so I think every one a picture in their mind of a bathroom, that fullfilled that list just nicely.

I had given him a minute and when the time was up, I asked the next guy to draw a blue print of that bathroom. I hadn’t told anybody at the moment but as you might have guessed, that list was going to be my spec analogy later on and the blueprint the architectural documents analogy.

3rd one at the white board was the only woman present and her task was choosing all the elements based on the two previous “documents”. She had to decide what specific sink should be used (brand/model), which tiles, basically all the hardware, or you could call them all the modules for her job was the module design analogy. The last person at the board had to do all the plumbing and wireing.

With those 4 “documents” on the white boards I asked each of the first three, starting with the woman, if the result of the previous stage was as she expected and if not what was different. In the end I asked the first guy, if it was the bathroom he’d dreamt of. Of cause the answer was no.

In plan of my head that was the first goal to have him say no. So we were still on track.
Keeping to my prepaared plan, I started from the buttom again, asking about what we could do prevented there erros they had pointed out at each transition.
All my questions had been preparred before hand and was all questions I ask my self, when I do peer review or write unit tests, so I was pretty certain, that the answers I got, would fit nicely into and entire hierachi of arguments for using the w-model. (which was my over all goal)

When we were done, all the listeners had a clear Idea of why so many errors are actually based in lack of requirements.
We all agreed, that what they had first thought to be requirement specifications for a bathroom at best was requirements but no way near specifications and that the lack of specifications was the source of the problem or in the terms of the first part by making those dreaded decisions they would actually increase the PPV not decrease it as they had first thought.

I’ve tryed getting that point across so many times and fail horribly in most tries. Taking something every one can relate to, a bathroom and making them make the errors, forcing them to take decisions based on lack of information, the point was suddenly much clearere.

They realized that no matter how hard you try to do your work as an achitect if you only have informations like: “spacious”,”lots of light” and “2 sinks” you are bound to fail. You can be the best Bathroom architect but you will never design the bathroom the guy who wrote the bullet list envisioned.

What I learned, was to use analogies everyone can related to and instead of telling people the conclusions of some arbitrary scientific study, to guide them with preparred questions to make those same conclusions them self.

So in the future when I’m have to tell people about write requirement documents. I’m not going to talk about building Applications or abstract things such as the v-model. I’m going to tell them about building bathrooms

In part 1, I wrote about some of the reasons I think requirement specifications often have a less than optimal quality. In this post I’ll try to proliferate.

Let’s look at a possible scenario:
The user wants to be able to create/edit and format texts online, no Flash or Silverlight is allowed only DHTML. The editor is going to be part of the company’s CMS.

It should be possible to:

  • Create new text documents
  • Edit old text documents
  • Choose the font type,size and color
  • See the contents in all browsers
  • Include pictures and sounds
  • Insert links
  • Use all Unicode characters

At first this might look simple but ok. However just digging a little we’ll find several problems. Most of them are based in an All-the-cool-stuff-should-reflect-back-on-us-and-al-the-bad-things-on-somebody-else way of thinking. So let’s dig and look at a few of those problems

“See the contents in all browsers”
The coolness of this requirement is of cause that the text will seems as intended in all browsers giving all end users the same experience.
The cost of the requirement would seem to be an incredible amount of testing but hi, thats somebody else’s problem.
A better requirement would be a fixed set of browsers. That would probably end up with a more user friendly editor increasing the coolness but that’s not so obvious to the person specifying the system so the fear of lowering the value will win.

How about choosing font type? This requirement leaves a lot of decisions to the developers
Should the font changes apply to the entire text or just a part of the text? Should the editor validate against design guide lines? believing that the developers will make the exact decision the users would want each and every time is a bit too naive.
Again the specification is leaving more unanswered questions than it’s answering.

Actually every single requirement in the list above has the same basic problem. I like to think of it as the “Demand a lot and make no decisions” problem.

The above requirements could be implemented as a online version of notepad, where the user would have to write the HTML by hand.
Even though it would meet the requirements it would be absolutely useless to the customer.
Then the developers and the customer could argue who were to blame.
One could argue that every requirement is met but for the customer to accept that argument would mean they had to acknowledge a loss of Personal Value, which they will be very unlikely to do.
Getting out of a situation like that with every body smiling is a skill on it’s own. My point is that the project ended up there and stays there for the same reason: PPV.

The trick is to act early to make the users realize that there’s a higher PPV in taking those domain specific decisions only leaving the IT decisions to the IT professionals. That’s where building bathrooms comes in which will be the subject of part 3.

In another post I referred to a survey, showing that the majority of errors are made in the specification phase.

I often wonder why it’s such a hazel, for the customer to specify what they actually want.

I was attending a change management meeting not so long ago. One of the pointers was, that we are all making the majority of our decisions based on “perceived personal value (PPV)”.

In the case of change management PPV is the value, that one thinks the change will have for one self.
That is, if my boss suggests to me, that we should change the way we test our deliverables. I will unconsciously evaluate the value of those changes to me.
If I think I’ll end up spenting more time without elevating the quality. I will not be as motivate to implement those changes, as if I think I’ll spent less time accomplishing the same results after implementing the changes.

Sounds pretty obviuos right? But just as important and not so obvious is: If I cannot see the value nor see a loss of value. I will still be more affraid of the loss of value than looking for the potential gain.

Basically PPV is all the coolness factor. If a change makes us look more cool, we welcome that change. If it doesn’t make us look cool, we’ll more often than not be afraid that the change will make us look uncool and hence we’re not overly excited about it.

Let’s try and apply the same logic to specifications.
The persons responsible for the specifications will want all the success of the application to reflect back on them self and the possible failures to be somebody else’s problem.

Bear in mind that no matter how bad the specifications might seem. The people writing them are doing their best to be as cool as possible. The problem is, that the way they unconsciously evaluate what’s “best”, might be and often is slightly off the target.

My favorite user argument for doing things the way they did, was that they wanted the specifications to be flexible. They did not realize that that was self contradicting.

Loooking through the PPV glasses they were so affraid of making decisions that might turn out to be lower their PPV that they wanted to be able to change their mind at any time.
At some point they did change their mind. Unfortunately to implement the wanted changes we would have had to rewrite the entire domain model.
Faced with a 50% cost increase they decided to stick with what they already had.

I’m sure, if they had been forced to make those decisions before hand. The fear of taking uncool decisions would have made them think more about use scenarios. Making them realize that subtle changes to the requirements was needed. I also know, if we had had those extra requirements from the start we could have implemented them with no extra cost.

I wish that we as developers could make customers realize that not taking decisions that might lower the personal value later on, is making a decision that will lower the personal value gained. I do however have an idea on this, that I’ll blog about later, which is where building bath rooms comes into play.

If my work was a person i would want it to be proud, stubborn and lazy.

Mr. Work should be proud to be reliable, fast and robust. He should be stubborn and think he was always right, at least until something or someone proves him otherwise. Mr. Work should then act as fast as possible to once again always be right.

Most importantly he should be lazy like no one else. If Mr. Work solves a task I want him to do that exactly once.
I do not want Mr. Work to reinvent the wheel. If he needs a wheel and it’s already there, he should be lazy and just use what’s already there. If no one has invented the “wheel” yet Mr. Work should take on that responsibility with pride.

If there are two tasks that involves similar subtasks Mr. Work should automate the subtasks and let the automation care about repeating the tasks.

Some might say that I’m a bit like Mr. Work and I know the people I’ve managed in different projects will say I try to conduct my work accordingly. I know this because I set up rules and guidelines to ensure those qualities.

One of the things I try to enforce to ensure reliability and robustness is making sure that what ever code I write or ask some one to write should fail fast.

To me failing fast includes:

  • Failing close to the source of the problem
  • Failing in the same development circle/iteration as it was created
  • Failing in the first possible project phase

When I think of phases in a development iteration I most often think of the v-model. The V-model not only describes the possible phases it also gives you a way to calculate the cost of not failing fast.

Each step you take in the model after creating an error and not realizing so, will make it 10 times as expensive to fix. That is if you create an error in the specifications, that would have taken 5 minutes to correct but you do not spot the error until you are done coding, it will take you 3,5 day in average to correct it.

That is a serious amount of work time wasted. So one of the things I like to do is to test documents. The usual specification is best described as a list of functions the user is guessing the system should be able to perform but very little on which tasks the users wish to solve and how they would like to solve it.
I personally do not accept this kind of specifications. For several reasons.

  • They are usually not very specific, and hence not specifications at all
    I’ve had such a document that said “The system should include a variety of functions, emails and such” I never learned, if they wanted to be able to write and send emails, wanted a web mail client, an web server or an email based service architecture.
  • They are close to impossible to test
    For some reason I’ve had several customers that thought that a good idea. AS they said it made for a more “Agile” project. What!, it just makes it easier for the customer to change their minds but harder to complete the project.
  • I don’t think the user should guess at how best to make a system solve certain tasks.
    The user knows a lot about the tasks they need solved. They should describe them and have faith that the IT professionals knows a lot about making systems that solves specified tasks

Use cases and User acceptance tests to the rescue. Having UCs and UATs you can’t just lean back you still have to work but at least now we have a proper specification on which tasks the user want to solve and how they want to solve them. We can use these documents as the basis of our work and we have a way of testing the feasability of those cases before even writing a single line of code.

Try to complete each UAT based on one or more UCs.
I’ve seen systems with UATs that had absolutely no corresponding UCs and I mean no UCs that came even close. Often it turns out that the first version of the UCs are poorly written.
I’ve been working on a system with a UC describing how to export data from the system. Everything until “press export button” was described in detail.

What should happen when the button was pressed was left out. Why? because it was obvious to all parties what should happen. As it turned out later; unfortunately the parties did not agree on what was so obvious.

In the project there was no UATs to begin with so when the first version was delivered the data was exported to an Excel spreadsheet however that was not what the users wanted. They actually just wanted to be able to print the data “exporting” it to paper.
A serious amount of code had been written to make exporting to spreadsheets (and other office formats) possible had been written and none of it was part of what the users wanted.

The rate of this kind of errors has fallen dramatically in that project since we introduced UATs giving us self the possibility of testing the specifications against how they will eventually be tested.

In the next part I’ll blog on failing close to the source