Stop Wasting Your Time – Don’t Bother Writing Functional Specs

burnt spec

OK – got your attention.

But I wasn’t being original. 37 signals got my attention with their article, Getting Real, Step 1: No Functional Spec. It was written back in Feb 2005, and when I found it today, it had 69 comments (and it was closed to future comments). Read the article to get started, and then read the comments – a fantastic debate full of insights on both sides of the argument.

My english teacher in high school had a great nugget of wisdom about writing argumentative essays. Mrs. Voss taught us that the viewpoints with the greatest potential for good writing were the ones with the strongest opposing viewpoints. I took her advice in college and wrote a compelling argument about why it was important to kill baby seals. My college professor believed that the grade of a paper was driven by the inherent “rightness” of the idea, and gave me a D. Eventually I realized that she taught me that knowing your audience is even more important than writing with technical proficiency.

Since you just finished reading a bunch of great comments from the linked document, I won’t reiterate the great arguments. Also I will try to avoid what Scott Adams noticed people do – “misinterpret [their] position, and then attack that misinterpretation.”

Creating a document no one uses is a waste of time. Spending time on documents people do use isn’t.

Don’t do it. Don’t use a functional spec to get superficial agreements and navigate the beurocracy that accompanies large projects. Don’t validate the specification trivially. Don’t deploy with a waterfall process (the spec is done, whew, now – on to design) and never revisit the spec. Don’t work with new developers, or remote developers, or anyone else who doesn’t have the context of direct eyeball-to-eyeball conversations with the customers. Also don’t hire any programmers without complete domain expertise in the customer’s business.

A functional spec is a single artifact, generated from a living repository of information about what needs to happen for a software project to succeed. It is not a static document. A solution can be described differently for different audiences and to achieve different objectives. The source code is a description of the functionality – a quite explicit one, describing exactly how it works (if you know how to read it). A design document, or a UML diagram, or an E-R diagram is another description of functionality – and it describes how a system is supposed to work. Most technical people can read a design document, but stakeholders may still be in trouble. A functional spec describes what a system is supposed to do without describing how the system does it. Larger audience, different objective. “Above” the functional spec lives a set of use cases, which describe how someone uses the system – again, different objective. “Above” the use cases lives a product strategy, or the objectives and benefits inherent in the system – what the system should enable, and why the system should do it.

When you have a cohesive strategy (Use price optimization software to maximize profits for my online bike shop), combined with complete, correct and consistent requirements (The software will model demand versus price…, The system will calculate the optimal prices based on that model, Product managers will approve prices before they are published to the website, and more…), you can create elegant designs, and implement great code.

The challenge is in using the functional spec appropriately in communication. Each “consumer” of the spec has a different objective – validating ROI, scheduling user-training, scoping the delivery, and more. It makes sense that they will want to see different pieces of the repository, presented in different ways. Misuse of a functional spec is a bad thing, but so is misuse of a car or an education. That doesn’t mean a spec is a bad thing, any more than an education is.

Waterfalls are just as bad for requirements as they are for development.

When you go sailing, do you spend all night reviewing the charts and planning your course, and making notations on the map? The next day, when you are on the boat – do you set the heading, validate that the compass reads what it’s supposed to, and then lash down the wheel and go below decks to watch tv until you arrive at your destination? Writing a functional spec, “freezing” or “baselining” it, and then moving on to development is no different.

My analogy is a little flawed. Software is a moving target. Imagine that you’re sailing towards another sailboat, which you expect to be at location X at time Y. Kent Beck got it right with Xtreme Programming Explained: Embrace Change (2nd Edition). Iterative development is key to success. If you try and make that work with a static spec, you’ve missed the boat. During the time that you spend developing the first rapid prototype, or the first release of the software, your goals have probably changed. Your prioritization of features almost certainly has. You develop new insights. Your environment changes. Your competition is not complacent. Revisit the specification the same way you revisit the implementation. Go back on deck, check your position and heading, and update your course.

Now those traceability diagrams have a lot more value. Your ability to describe the big picture, change it, and quickly appreciate the ramifications of making those changes will make you more competitive.

[Update: Waterfalls aren’t always bad. In this comparison of waterfall and incremental processes, we see when they can be good]


I had the opportunity to meet with Kent a few years ago, and he made a great point. His experience was that people who were burned by lack of testing swear by testing. People who’s projects failed due to lack of design tout the benefits of up front design. People who failed by delivering great software that didn’t meet the user’s needs become champions of requirements. We’re all reactionary, says Kent.

The key is realize that all of these things are important, but none of them are a panacea. Leave any of them out at your own risk. Over-emphasize or mis-apply any of them at your own cost.

Requirements are important. Functional specs are useful. Just don’t misuse them.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.