Functional specs matter

OK, I’ve decided to take the opposite extreme to the 37signals crew because extremes seem to cause people to pay attention. So, here’s my extreme statement:

Functional specs matter. If you don’t use them, the probability of building anything well and building it on time is next to zero.

Now Jason Fried seems to have a different opinion. He basically says:

Don’t write a functional specifications document. Why? Well, there’s nothing functional about a functional specifications document…. Functional specifications documents lead to an illusion of agreement…. Functional specifications document are “yes documents.” They’re political. They’re all about getting to “yes” … Functional specs are often appeasement documents. They’re about making people feel involved….

He’s got lots more to say but that’s it in a nut shell. So, how does Jason propose to build software instead?

We suggest building the interface first and using the actual screens as the functional spec. There are times, however, when the interface doesn’t provide all the information required for the programmer to hook it up. Designers should always present the programmer with the multiple states of an interface element so the programmer understands what to display when this or that happens.

Hmm, giving the programmer extra information so she understands exactly what a mockup is communicating. That sounds like a functional spec to me. In another post Jason describes some work he was doing on the Files section of Basecamp:

Step one: Make a mental list of the must-haves. You have to know what you’re designing. I looked at the current ‘Upload a file’ screen and decided these things must stay:

  • The ‘Choose file’ widget
  • An optional description
  • The privacy checkbox
  • Email notification

Step two: Sketch a layout on paper. The sketch includes the must-haves…

Step three: Make the screen. Thinking and sketching took me 10 minutes. Creating the real screen and updating the code can take two or three hours.

Jason likes to keep things very light. Outline what you want to do mentally or jot it down quickly, then make a quick sketch. If the sketch looks good (presumably he floats it past a few folks), migrate the sketch to a real screenshot, with story as necessary, so a programmer knows what to build.

This is where I become confused in the “don’t write functional specs” mantra I continually see from 37signals (yet another today). The purpose of a functional spec is to decide what you want to build before you build it. Why do you do it? To save unnecessary thrash during actual building. 37signals absolutely does this. So, in my mind they are building functional specs.

So, functional specs do matter. They even matter to functional spec haters. 🙂 But if they’re so useful, why are there haters? As Jason correctly points out, lots of company have sole positions that write specs and toss it over the fence to developers to build. In some cases these spec writers rarely interact with anyone before writing the spec. This is really a poor way to build software because you’re not leveraging the unique perspectives and talents of everyone on your team or your customers (aka Wisdom of the Crowds).

The best software in my experience is built by a small group. Also, faster cycles (for most projects) are better than longer. The quicker to market you are, the faster you’ll know whether your idea works, needs more iterations or simply sucks and should be removed.

The points of wisdom I take away from Jason and company is keeping your documentation as light as possible, keeping cycles short and hearing your customers. His catch phrase of “Getting Real” is perfect in this regard. But “Don’t build functional specs,” while a good attention grabber may end up leading small, new development shops in the wrong direction. Given 37signals really is writing functional specs, this advise is really misguided in my opinion.

The write message for small developers is “Functional specs matter.” Know what you want to build before you build it.


3 Comments on “Functional specs matter”

  1. Greg Pfeil says:

    Well, I think 37 Signals is trying to say something different from what you’re thinking:
    “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.”
    See, it’s these “paragraphs of text” that get in the way. It’s not bad to decide what you’re doing before you do it, but it’s much better to show a mockup than to _describe_ the mockup.
    “We write a one page story … Then we begin building the interface — the interface is the functional spec.”
    I imagine there’s also a bit of not-planning-too-far-ahead involved. Functional specs often talk about what will be done over a year or more, when really you need to limit your foresight to a month or two at a time, and see where the road goes.
    (Quotes from
    Also, (at least in preview), there seems to be no formatting of the comments, even my paragraph breaks disappear.

  2. Greg Pfeil says:

    ok, the paragraph thing is _only_ in the preview, looks ok when posted.

  3. Andrej Gregov says:

    Good points on the illusion of agreement and mockups. In my experience functional specs have included screen shots. So, maybe Jason means requirements documents? Those tend to be “agreement” type documents. But again, in my mind a requirements document isn’t specific enough to have to worry about what everyone imagines. The specific functionality for an app is supposed to be specified in the functional spec. There should be no ambiguity once a proper functional spec is complete.
    The thing that bothers me about the current rhetoric from 37signals is that they’re essentially communicating they don’t believe in specifications when in fact they are producing them (whether requirement docs, functional specs or a mixture of both).
    I used the “functional specs matter” mantra to simply illustrate the opposite extreme. Either extreme taken at its literal level misses the point. The right message IMO is keeping your specs light, iterative and tightly focused. While the 37signals crew does communicate this, I feel these messages are overshadowed by “don’t do functional specs”. It’s such a controversial statement to many dev shops because it essentially means, “skip spec writing.” That’s the wrong message to be sending to new app developers.

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