Post written in 2008 but still relevant I think

For those of you who, like me, find themselves in an old-school waterfall development environment (reminder to self: ask more questions in the interview next time!) you have to deal with more detailed specification documents.

Here’s the scenario:

You are a developer handed a detailed specification/design document. It seems fine at first but sooner or later you discover some mistakes and omissions. Or, as is especially the case with those badly written spec documents that describe “how” rather than “what”, you realise you have a better idea. Or maybe you just have digested the spec enough to realise that they might actually want something else?

What do you do?

Option 1: Get on with it

Many developers will just take the easy way out and get on with it. It might take much longer because of the sub-optimal requirements but it is easier to just get on and code than “rock the boat” by passing things back up the line. We’d much rather code and get stuff done than sit around and talk about how and what (and worse, get involved in office politics).

But what typically happens is that the design doesn’t hold together well. The user experience is substandard. There is far more code to maintain. And then the change requests come through wanting changed what you anticipated needed changing at the start! And now you only have time to hack in the CR changes when really you’d ideally make major changes to the design. Remember, this is a waterfall environment--minimal allowance for rework!

Option 2: Challenge it (change the spec)

A specification or requirements document is just a snapshot in time, written typically by one fallible person with a limited understanding of both the technology and business side and usually weak on one side or the other. Don’t think of it as being set in stone!

There have been many times I have successfully campaigned for a change to requirements to the betterment of both the technology solution and the business. A good trust relationship with a knowledgeable business representative is key. This shouldn’t be hard! The reality is you want to give them what they want. They want what you want as well: a good technology solution that can be developed efficiently and maintained in the future. You might be surprised how open even the original author of a requirements document is to feedback and questions.

My View

I have tried both approaches many times and found the above results. I have found it is far better for everyone to voice concerns or ideas. You’d be surprised how receptive people are.

I have had other developers come to me after finding something I have done that doesn’t quite match the spec. They speak as if the specification document trumps all and therefore the code must be wrong! My initial answer is sometimes along the lines of “reality is stronger than than a specification document. It is the specification needs to be changed!”. It sounds arrogant but as a developer you get to understand a system and the user’s requirements at many levels deeper than most. And because of that, you should be able to relatively easily prove that your implementation meets real business requirement better than the specification. Obviously in this case it would be better if the spec had been changed first. If you have a good relationship with the spec maintainer you can get approval ahead of official changes.

Of course agile advocates might say “the implementation is the specification” and keep requirements documentation light and interaction with end users regular. I couldn’t agree more. However, as I said at the start, if you are (hopefully temporarily) stuck in an organisation with a waterfall mindset and methodology you have to find the best way to deal with these inevitably flawed requirements documents.