November 27, 2005
The guys at 37signals think functional specs are worthless:
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. 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.
Functional specs are often appeasement documents. They're about making people feel involved. But, there's very little reality attached to anything you do when the builders aren't building, the designers aren't designing, and the people aren't using. We think reality builds better products than appeasement.
Functional specs are about making decisions before you have enough information to decide. They are about predicting the future and we all know how accurate that is.
In lieu of a functional spec, the guys at 37 Signals recommend writing a simple one page story of what the app should do. This probably isn't a functional spec in the traditional sense; it's more like a vision statement. And you should have a vision statement, because half the developers on your team probably can't tell you what they're building anyway.
Linus Torvalds evidently hates functional specifications, too:
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. There are two major reasons to avoid specs:
- They're dangerously wrong. Reality is different, and anybody who thinks specs matter over reality should get out of kernel programming NOW. When reality and specs clash, the spec has zero meaning. Zilch. Nada. None. It's like real science: if you have a theory that doesn't match experiments, it doesn't matter how much you like that theory. It's wrong. You can use it as an approximation, but you MUST keep in mind that it's an approximation.
- Specs have an inevitable tendency to introduce abstraction levels and wording and documentation policies that make sense for a written spec. Trying to implement actual code off the spec leads to the code looking and working like CRAP. The classic example of this is the OSI network model protocols. Classic spec-design, which had absolutely zero relevance for the real world. We still talk about the seven layers model, because it's a convenient model for discussion, but that has absolutely zero to do with any real-life software engineering. In other words, it's a way to talk about things, not to implement them. And that's important. Specs are a basis for talking about things. But they are not a basis for implementing software.
So please don't bother talking about specs. Real standards grow up despite specs, not thanks to them.
In defense of functional specs, there's a rebuttal of Linus' position at Canned Platypus. And Joel has a persuasive three-part essay championing functional specifications that's chock full of great advice; I highly recommend reading all three parts. Unfortunately, you know you're in trouble when Joel tells you how hard it is to write functional specifications that people actually read:
The biggest complaint you'll hear from teams that do write specs is that "nobody reads them." When nobody reads specs, the people who write them tend to get a little bit cynical. It's like the old Dilbert cartoon in which engineers use stacks of 4-inch thick specs to build extensions to their cubicles. At your typical big, bureaucratic company, everybody spends months and months writing boring specs. Once the spec is done, it goes up on the shelf, never to be taken down again, and the product is implemented from scratch without any regard to what the spec said, because nobody read the spec, because it was so dang mind-numbing. The very process of writing the spec might have been a good exercise, because it forced everyone, at least, to think over the issues. But the fact that the spec was shelved (unread and unloved) when it was completed makes people feel like it was all a bunch of work for naught.
Also, if your spec never gets read, you get a lot of arguments when the finished product is delivered. Somebody (management, marketing, or a customer) says: "wait a minute! You promised me that there would be a Clam Steamer! Where's the clam steamer?" And the programmers say, "no, actually, if you look on the spec on chapter 3, subchapter 4, paragraph 184.108.40.206, you'll see it says quite explicitly 'no clam steamer.'" But that doesn't satisfy the customer, who is always right, so the grumpy programmers have to go retrofit a clam steamer into the thing (making them even more cynical about specs). Or a manager says, "hey, all the wording on this dialog is too verbose, and there should be an advertisement at the top of every dialog box." And the programmers say, in frustration, "but you approved the spec which precisely listed the layout and contents of every dialog box!" But of course, the manager hadn't actually read the spec, because when he tried, his brain started seeping out through his eye sockets, and anyway, it was interfering with his Tuesday golf game.
So. Specs are good, but not if nobody reads them. As a spec-writer, you have to trick people into reading your stuff, and you should also probably make an effort not to cause any already-too-small brains to leak out through eye-sockets.
If it takes a writer as good as Joel to trick people into reading functional specs, the rest of us are totally screwed. I guess that's hard to see when you're Joel, but it's been obvious to me on every project I've ever worked on.
Having spent the better part of the last two months writing functional specifications, I'm of two minds on them:
- Yes, you absolutely should plan what you're going to do before you do it.
- No, you shouldn't try to plan everything you do in excruciating detail, because you'll forget a million things, then on top of that you'll encounter a bunch of problems you hadn't even considered, so you'll end up rewriting it all anyway.
You have to strike some kind of balance between a one-page vision statement and an obsessively detailed five volume masterwork of a functional spec. I can't tell you what level of specification is appropriate for what you're doing, but here's what has worked for me:
- When in doubt, err on the side of that one-page vision statement. At least people will read that. Maybe.
- Plan a little, then code a little. Repeat. Planning and implementation should overlap; they're symbiotic processes. Too much planning is just as wrongheaded as no planning.
- Your spec should be a dynamic, living document. It should change and grow along with your code. Have you considered making your spec a Wiki?
Posted by Jeff Atwood
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:
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.
anyone have recommendations on a wiki that is good for spec authoring?
This discussion is great, and points out why a lot of software projects are now being delivered as Time and Material. Software is still a young field, and with such differing opinions on how and what should be delivered, it begins to make sense to play it safe, and agree to charge for time and not a deliverable.
With a TM project, your client has skin in the game, and will help you be more efficient.
If you have to write a fuctional spec, at the least make sure it has a list of high level requirements up front. Don't expect the person reading the spec to sift through pages and pages to extract the basic requirements.