Heads up! This page uses features your browser doesn’t support. Try a modern browser like Firefox or Chrome for the best experience.

Don’t write a functional specifications document

These blueprint docs usually wind up having almost nothing to do with the finished product. Here’s why:

Functional specs are fantasies

They don’t reflect reality. An app is not real until builders are building it, designers are designing it, and people are using it. Functional specs are just words on paper.

Functional specs are about appeasement

They’re about making everyone feel involved and happy which, while warm and fuzzy, isn’t all that helpful. They’re never about making tough choices and exposing costs, things that need to happen to build a great app.

Functional specs only lead to an illusion of agreement

A bunch of people agreeing on paragraphs of text isn’t a true agreement. Everyone may be reading the same thing but they’re thinking something different. This inevitably comes out later on: “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 specs force you to make the most important decisions when you have the least information

You know the least about something when you begin to build it. The more you build it, the more you use it, the more you know it. That’s when you should be making decisions — when you have more information, not less.

Functional specs lead to feature overload

There’s no pushback during spec phase. There’s no cost to writing something down and adding another bullet point. You can please someone who’s a pain by adding their pet feature. And then you wind up designing to those bullet points, not to humans. And that’s how you wind up with an overloaded site that’s got 30 tabs across the top of the screen.

Functional specs don’t let you evolve, change,and reassess

A feature is signed off and agreed on. Even if you realize during development that it’s a bad idea, you’re stuck with it. Specs don’t deal with the reality that once you start building something, everything changes.

So what should you do in place of a spec? 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. This process shouldn’t take more than one day.

Then begin building the interface — the interface will be the alternative to the functional spec. Draw some quick and simple paper sketches. Then start coding it into html. Unlike paragraphs of text that are open to alternate interpretations, interface designs are common ground that everyone can agree on.

Confusion disappears when everyone starts using the same screens. Build an interface everyone can start looking at, using, clicking through, and “feeling” before you start worrying about back-end code. Get yourself in front of the customer experience as much as possible.

Forget about locked-in specs. They force you to make big, key decisions too early in the process. Bypass the spec phase and you’ll keep change cheap and stay flexible.

Useless Specs

A “spec” is close to useless. I have never seen a spec that was both big enough to be useful and accurate.

And I have seen lots of total crap work that was based on specs. It’s the single worst way to write software, because it by definition means that the software was written to match theory, not reality.

—Linus Torvalds, creator of Linux (from: Linux: Linus On Specifications)

Fight the blockers

I found the people insisting on extensive requirements documents before starting any design were really ‘blockers’ just trying to slow the process down (and usually people with nothing to contribute on design or innovative thinking).

All our best work was done with a few concepts in our heads about improving a site, doing a quick prototype (static), changing the design a bit and then building a live prototype with real data. After kicking the tires on this prototype, we usually had a real project in motion and good result.

—Mark Gallagher, corporate intranet developer (from Signal vs. Noise)

We made Basecamp using the principles in this book. It combines all the tools teams need to get work done in a single, streamlined package. With Basecamp, everyone knows what to do, where things stand, and where to find things they need.