Dysfunctional Specifications

The guys at 37signals think functional specs are worthless:

This is a companion discussion topic for the original blog entry at: http://www.codinghorror.com/blog/2005/11/dysfunctional-specifications.html

The one thing I really liked about Joel’s advice was the emphasis on Functional specs vs. Technical specs. A functional spec should be written from the perspective of the user, with user scenarios. It’s not technical.


Joel says that “Details are the most important thing in a functional spec.” Details are important, but they’re also

A) the thing that is hardest to get right – even when talking about “just” the UI

B) the thing that typically makes a spec hard to read. Reams and reams and REAMS of mind-numbing detail.

That’s why I advocate keeping the spec a “big picture document.” It’s easier to do this in bite-size chunks: plan a little, code a little, then repeat that cycle as many times as necessary.

It really depends on your client and how reasonable they are to changes.

One thing I think is extremely important is acceptance criteria along with lightweight functional specs (ala Joel).

Our client is killing us with minor changes and we unfortunately don’t have clear acceptance criteria to push back with (we came in midstream).

Interestingly, I have been writing one-page specs on a wiki. I’ve also put list of tasks at the top of the page, which are struck through when completed. This encourages people to read the spec, as the to do list is on the same page.

The biggest problem with specs is they are written with too much detail in advance. You should probably document who is going to use your system and very briefly each thing they are likely to do with it, and why this functionality is needed to get an idea of the likely scope of your system.

Then prioritise one or two of these, think in more detail about the technical nature of how they should be implemented, implement them, demonstrate them to your users, and select a few more requirements until everything is complete. As you do this you’ll learn what your users really want, and everyone will feel involved in the process.

The best projects I have been on have had vision statements like you mentioned. Then a lot of interaction though-out the development process. When new things were discovered, designed or agreed upon then we would write that down too. It seems to me that the goal of the all exhaustive spec is to eliminate the need to think, communicate or design once the development process gets started. My experience says that is a pipe dream.

As a QA person/Business Analyist part time developer I disagree and agree.

I disagree in that not having a list of features IMHO is a very poor way to meet the needs of the end users. That is, unless you have the luxury of being a true agile development group have users verifying at each build… although even then scope creep could make the project last too long. It seems like a firm deadline would then be required to stop the project from growing out of scope budget boundaries.

I agree in that writing overly detailed specifications is not useful. Although I have not had the opportunity to see them in action, I suspect this is what use case diagrams are for, to describe how the system will work without getting into details. Additionally they are likely to make it easy for end users to understand. The problem with use case diagrams seems to be that making effective ones is difficult.

I agree with the vision statement though, one of the few areas where a vision statement might actually be useful.

– Matt wrote:
agile development . . .although even then scope creep could make the project last too long

One of the points of Agile Development is that the user stories, or features, are ranked by priority. The developers implement them until the user says enough is done, or time is up. So the project cannot last too long unless the users have unrealistic expectations and authorize the project to keep going so the kitchen sink will be included.

I firmly believe you have made a valid point Scott re: billing. For example, most smart tradesman have a flat call out fee then charge by the time from then on. It’s an effective way to control scope creep.

i’ve not spent much time reading up on Model Driven Architecture, but i have spent some time looking at Database Driven Development.

both look either past the notion of Functional Spec, or implement a FS directly. kind of.

i think they’re much the same, although MDA has more MindShare. codefutures.com is a commercial implmentation of DDD, and last time i looked, had a demo on their site. the notion: the database is the spec and all code is generated therefrom. the advantages: the vocabulary is reduced to normal forms, which is an implementation of just logic; with a single point of failure there is also a single point of success; and lastly, no matter how you cut it, in the end, data integrity is the responsibility of the database so let’s start at the beginning (or end, depending on your POV).

lots of coders dislike MDA, generally out of paranoia that it’ll make them redundant (in the Brit sense). could be.

That’s why I advocate detailed, every-changing spec documents. I also advocate billing by the hour rather than quoting a flat fee. That way you gets yo money when the client changes their mind for the 100th time.

I’m not sure about the utility for developers of reading a spec. However, I’ve found having the development team write a spec to be really useful.
Also, if you have a spec with costs associated with features (and you have costs associated with changes), customers tend to focus more on what they need, rather than “Oooh, I’d like that.”

Well I don’t understand the point of the article. So because no one knows how to write a functional spec, they shouldn’t be done? Why hell then, we should all stop development now. Most programmers are so damned inept with or without any kind of specs that if some kind of objective being came down and saw the mess that is most development they’d forbid people from ever writing another if statement again.

What’s missing here is that the development team needs to not only outline what they’re going to do, but also what they’re not going to do. I find that extremely vital, as customers really tend to focus on that, and that suitably narrows their focus so much that they actually do start concentrating on what they’ve agreed on doing.

Oh, and clients are very good at manipulation, and developers are very poor at recognizing it. The client is well aware that they were never promised a Clam Steamer. They feign ignorance to get their way, since they obviously promised to someone else somewhere and are trying to deflect the blame to the development team instead.

Well I must rock then, because I’ve written functional specs many, many times and they’ve helped greatly. As with anything else, it’s part of a greater whole, and must be treated as such.

Well I don’t understand the point of the article. So because no one knows how to write a functional spec, they shouldn’t be done?

The point is this: Because it’s easy to create a trainwreck with a misguided functional spec, keep your spec as simple as possible.

How simple is “possible” depends on what you’re doing, of course. Who knows, maybe you’re building the space shuttle…


There are a number of really good reasons to have specs longer than a page:

a) scheduling
b) budgeting
c) complexity

Once your company is more than a handful of people, being able to get a sense of when you’ll be done and what it will cost to get there is kind of important. Believe it or not, non-Web 2.0 apps still exist - and some even run on legacy platformss!

Complexity is an important point. Very often, the people doing the coding don’t understand the subject domain. It is highly unlikely that developers will ever develop the same level of domain expertise as the target customers (although some would be nice). In the absence of that knowledge level, how do you ensure that user needs are met? You can’t iterate infinitely.

So, yes, you can write Backpack or Basecamp with a vision statement. But, you couldn’t write MS Project or MS Word with one- not if you wanted it to get to market in your lifetime. (Let’s not get into the argument of whether those 2 apps are abominations, shall we?)


Programmers in the real world will tell you that specs aren’t worth the paper they are written on. They are half-baked informal descriptions that are too abstract to be understood by the users, and too imprecise to be useful to the programmers. They are full of internal inconsistencies and factual errors, because there is no way to test them. They are obsolete the day they are published, because it is too difficult to rewrite them as the system becomes better understood. Things are no better with the other standard commodities of development: project plans, schedules, cost estimates, and documentation.

I know this topic is old but I thought I’d add my two cents :-p

On the project I just completed we used a Lotus Notes BBS (Exchange Shared Folders) for our specifications. Instead of having one giant document no one reads and only one person can edit we had a Notes BBS which is a threaded topic based system.

So, Imagine the outline of a functional spec where each topic and sub topic becomes editable by anyone and commentable by anyone on the team and separated out by sub topic.

The advantages are

*) there isn’t one big spec to read and get bored by. You can go directly to the section you need to implement or comment on.

*) Notes or Exchange track read/unread per entry so every person on the team that needs to know that one small part of the spec was changed will know immediately. No having to dig through a 100~1000 page document. The topics have have been updated are bolded by Notes/Exchange

*) If an issue comes up any user can edit the original spec or add a reply (sub topic). This facilitates discussion and gives a place for the results of that to actually be recorded

*) Any ideas now have a specifc place to be added. Have an idea for how to improve feature XYZ, add a comment in the BBS

*) Both Notes and Exchange make it easy to paste in graphics. A diagram or screenshot is a simple operation. (unlike say a wiki where it’s a slow and painful operation)

*) Both Notes and Exchange make it relatively easy to edit color coded tabular data. For those times when tables are important it’s much better than a word document or trying to edit tables in a wiki or HTML.

*) This also facilitates creating the spec as you go. The only thing you need to start is some part of your outline as starter topics in Notes or Exchange.

Having done it this way I never want to go back.

I’ve tried the wiki-based spec, but it seems to go unread and unmaintained after I create it, even if it’s only 30 lines long.

More than anything else it seems like the problem is others’ lack of care for organization and process. I feel like a high school teacher trying to think of ways to coax students into participating in the process and ensuring that quality products are shipped.

We end up relying mostly on design comps which are obviously far short of a spec, so many features end up coming out as the programmer inferred them from a comp instead of how they were planned by the product team.

Maybe the spec needs to be some sort of game. People like games. Argh.