The Sieve Theory of Functional Specifications

We’re working through an overhaul of our software development lifecycle at a company I’m consulting with right now.

In the couple years before I came on board, there were a few horror projects that were 100% over schedule, lack of communication, tons of problems right after launch, etc. etc.  The then-CTO has left to spend more time with his family, and the new guy (my direct boss) is doing the smart thing and pushing Agile concepts pretty hard.  However, we have a consulting agency in that is very familiar and comfortable with classic waterfall methods, so we find ourselves duking it out over SDLC philosophy as we work towards common ground.

Currently we’re talking about functional specs.  To my mind, the functional spec outlines what we’re going to build, and how it should work.  That’s where we all agree.  The disagreement starts pretty soon after that.   I believe specs should be human-readable.  I believe specs should only be detailed where necessary, and that unnecessary or obvious detail just leads to confusion.  I believe pictures tell a thousand words, and fake screenshots are super valuable.  I believe specs should be brief.

Most contentious, perhaps: I believe specs should be written at multiple contextual levels, in order to most effectively relate the information.  I believe specs should get the big picture right before drilling into endless details.  I might refer to this as the sieve theory of specifications: if your discourse is limited to a single level and get too detailed, your spec ends up like a sieve, and you risk letting important points about the application fall through the gaps because of confusion and lack of perspective.

Tell a story about each feature in the software, and fill in detail only where you need to.  Show a nice picture (learn to use Visio).  Use readable language.  Don’t clutter up your spec with endless lists of bullet points or nightmarish levels of outlining.  Don’t write your spec like you’re writing a legal brief, with SHALLs and WILLs and SHOULDs and MUSTs and MAYs and CANs all competing for thinking space.

While googling for “worst functional specification” and “terrible functional specification”, and coming up with zero results (very interesting!) I found the Getting Real 37 Signals website and like this quote very much:

Go with a briefer alternative that moves you toward something real. Write a one page story about what the app needs to do. Use plain language and make it quick. If it takes more than a page to explain it, then it’s too complex.


2 Responses to “The Sieve Theory of Functional Specifications”

  1. 1 Damon September 5, 2008 at 9:32 pm

    I like most of the stuff that comes out of 37 Signals. Yes, I’m fully on the band wagon. That aside, I enjoy their writings because they articulate the business value of an agile philosophy in plain language without resorting to “…for Dummies.” I haven’t seen anyone successfully do that without resorting to either academic or engineering speak.

    Regardless of the approach, I think the question that doesn’t get asked enough is a simple “Why?” “Why are we building a complex functional spec?” “Why does creating a document generate value for the business?” “Why, why, why, why, why?”

    I know I’m preaching to the choir but perhaps if you can put the question of value to them, it might get them to see that very little value exists in something that will become irrelevant the moment it hits the file share, which will also have some sort of crazy structure. I say this having been the guy that demanded the “complete” functional specification…

    On the flip side, it is possible that such a document can generate value in the sense that a contractual obligation exists. Of course, it doesn’t really help anyone…but I’ve also found that shifting my mind set to “well, it adds value because it must be done before we get paid” helps me spin such a massive waste of effort into something more mentally positive.

    Rambled on a little there…

  2. 2 Wyrd September 11, 2008 at 9:44 am

    I think you’re probably right most of the time. The only time I can see a super-detailed, bulletted spec being of value or necessary is when you’re writing the core of something that has to be highly reliable, highly secure or both. Like inside an ATM or an anti-lock breaking system or a pacemaker or a voting machine. (Of course I rather doubt Diebold uses a sophisticated system for writing their software.)

    Furry cows moo and decompress.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

TwitterCounter for @anthonyrstevens
Add to Technorati Favorites

RSS Feed

View Anthony Stevens's profile on LinkedIn

%d bloggers like this: