On Functional Specs and Project Pitfalls

By Christopher Hawkins •  Updated: 02/16/05 •  5 min read
Revised on 13 May, 2015

I found a good post about functional specs when I was reading Ian landsman’s blog this morning.  Ian notes the different opinions on whether or not writing functional spec is a good idea – one camp claiming that spec is purely a political appeasement move, and the other claiming that  spec is vital to a well-written app – and ends up coming down on the side of those of us who write functional specs.  Good show, Ian!  He also wisely notes that functional spec is best done in small bits.  I agree – the bigger a single iteration of spec is, the more likely it is you missed something.

There is a reason that I included inadequate/unclear requirements amongst The 5 Pitfalls of Estimating a Software project – this problem is HUGE in the industry and it cannot be solved by saying “specs don’t work – don’t write specs.”  It’s true that ultimately you need people to agree on the functional spec, just as it is true that they eventually need to agree on a user story or an interface mock-up.  This doesn’t not make the functional spec an appeasement document, though.  If anything, the process of developing a functional spec should get people talking about – even fighting about – what task experience the app needs to provide.  The biggest fear a developer has is to deliver an app only to be told “that’s what I asked for, but it’s not what I want,” and the process of developing a functional spec – done correctly – will avoid this. That’s why I’ve always advocated that every project needs at least – dare I say it – a small spec.

Having said that, I’m going to leave this here:

SmallSpec - painless functional specs

SmallSpec – painless functional specs

Ahem.  Moving on…

Why did I qualify my previous statement with “done correctly?”  Simple – too many developers have an “order taker” mentality when it comes to developing a functional spec.  A client or project manager will rattle off a list of wishes – “Yeah, this program needs to cure cancer, gnarfle the garthok, walk my dog, do my taxes, and make me a sandwich.  It’s pretty simple, you should be able to do it in about 2 hours.”  Now, at this point the developer can go one of two ways:

  1. Say “yes, sir” and shuffle off to make a half-hearted attempt at doing what he knows is impossible, only to be driven to drink and beat his children when hopelessness finally sets in, or
  2. Push back on the client or project manager, challenging their demands; “no, that doesn’t fit in-scope (unless we make adjustments elsewhere in the project)

I’ll give you three guesses what a good developer will do.  😉

When developing a functional spec, it is your obligation to act in a consultative fashion and challenge your clients assumptions and requests.  This is not McDevelopers – you don’t simply serve up whatever the client in the drive-thru orders through the speakerbox.  It is your job to protect the client from himself.  If you find that even after developing a functional spec, the delivered app is met with “that’s what I asked for, but it’s not what I wanted,” then odds are you have failed your client in some way.  Note that I did not say the spec has failed – you have failed.  Perhaps you didn’t probe deep enough.  Perhaps you let some assumptions slide.  Perhaps you didn’t lay out the different scenarios your client’s requests could lead to clearly enough.  I’ve been there, and it is painful to not only let your client down but fall flat on your face with your release.

Controlling scope creep is also part of doing functional specs correctly.  One can claim that functional specs inherently lead to scope creep because it is easy to add something to a Word document, but I disagree.  I think weak developers lead to scope creep.  Again I say – a good developer will not allow this to happen.  A good developer will push back.  “This change conflicts with xyz” or “This change will double the cost of abc” or “This change is not technically feasible,” etc.  When it is obvious that the scope of the project is in jeopardy of changing, a good developer will speak up and offer suggestions.  In some cases, the developer must be willing to stand firm and say NO.

Functional specs don’t fail.  Developers do.

To be fair, the “don’t write functional spec” guys were primarily designers at the time, although over the years they’ve built one hell of a software empire, and presumably still don’t believe in functional spec.  Even so, a designer is dealing with a different set of concerns than a developer is.   I get the impression that some people have a mental image of a functional spec that is just a massive, Steve McConnell-style Word doc with endless bullet points and no interface examples.

This is not how I do my specs here at Cogeian Systems.  Rough wireframe UIs are always liberally sprinkled throughout my functional specs to illustrate what the text is describing.  However, I don’t go into tremendous detail in the spec, nor do I go off building a real, functioning UI until it has been decided what that UI should do, and how it should do it.

A good functional spec should get you on the right side of the 80/20 rule.  Given that, it’s natural to allow for some discovery-as-you-go. And as you make these discoveries, your spec should become enlightened as you do.

I will stick with the approach that has made my projects successful – committing the application experience from a user POV down on paper in an appropriate level of detail in the form of a functional spec – and vetting it with the users – before writing a line of code or building a working interface.