This is an archival post from my newsletter. Join the newsletter to get in the loop.

Functional Specs, To Do or Not To Do

OK I really have an entire essay I’d like to write on this, but I’m already working on another and don’t have time so I’ll just throw this out there. I read this on the Signal vs Noise blog yesterday and it kinda blew my mind:

*”Don’t write a functional specifications document. Why? Well, there is nothing functional about a functional specifications document.

Functional specifications documents lead to an illusion of agreement. A bunch of people agreeing on paragraphs of text is not real agreement. Everyone is reading the same thing, but they’re often thinking something different. This inevitably comes out in the future when it’s too late. “Wait, that’s not what I had in mind…” “Huh? That’s not how we described it.” “Yes it was and we all agreed on it – you even signed off on it.” You know the drill.

Functional specifications document are “yes documents.” They’re political. They’re all about getting to “yes” and we think the goal up front should be getting to “no.” Functional specs lead to scope creep from the very start. There’s very little cost in saying “yeah, ok, let’s add that” to a Word document.”*

The main part I find striking about this is how much it contrasts with the Joel Spolsky method, which I’ve used in the past:

“Software engineers who dive into code without writing a spec tend to think they’re cool gunslingers, shooting from the hip. They’re not. They are terribly unproductive. They write bad code and produce shoddy software, and they threaten their projects by taking giant risks which are completely uncalled for.”

Doesn’t really get more far apart than that. Since the SvN guys seem to be more in the design realm and Joel is a Microsoft guy perhaps there vastly different viewpoints make sense? I’m going to have to think about this a bit more.

Personally I tend to write short specs. I exclusively use an outliner for this process. I think it’s much more productive to be able to open and close parts of the spec than have a big scrolling Word doc to deal with.

[cm_simple_form id=3]