Ian Landsman is Starting From Scratch, February 12, 2005:
Functional Specs, To Do or Not To Do
If you're in the market for a powerful and user friendly Help Desk solution, please take a look at my company's flagship product HelpSpot.OK I really have an entire essay I'd like to write on this, but I'm already working on another and don't have time so I'll just throw this out there. I read this on the Signal vs Noise blog yesterday and it kinda blew my mind:
"Don't write a functional specifications document. Why? Well, there is 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."
The main part I find striking about this is how much it contrasts with the Joel Spolsky method, which I've used in the past:
"Software engineers who dive into code without writing a spec tend to think they're cool gunslingers, shooting from the hip. They're not. They are terribly unproductive. They write bad code and produce shoddy software, and they threaten their projects by taking giant risks which are completely uncalled for."
Doesn't really get more far apart than that. Since the SvN guys seem to be more in the design realm and Joel is a Microsoft guy perhaps there vastly different viewpoints make sense? I'm going to have to think about this a bit more.
Personally I tend to write short specs. I exclusively use an outliner for this process. I think it's much more productive to be able to open and close parts of the spec than have a big scrolling Word doc to deal with.
Discussion
Ian,
You are correct. SvN is by designers for designers. Of course any designer who is in charge of creating a full blown web application (read Basecamp) will be very frustrated if he will have to write a spec on the programming level. Of course a designer would prefer to create a series of intereface sketches instead.
For me there is sense in both approaches, but only combined. Its good to have an interface mockup *and* a functional spec in any form at the beginning of a project.
Created by Sergey on 02.12.2005 1:02 am
I agree with your last comment Ian. This would have to be optional feature of the reader though otherwise there'd be too much noise. I wish I could toggle comments from a post on an off in BlogLines.
On the main point, I couldn't agree more with Joel. In my experience in enterprise development, where there's been no spec (no matter how thin) it's always been a failure.
I would say it's iterative though. For the first phase of development a spec is imperative. For the next, maybe not, a signed-off feature list (which I suppose you could call a spec) would suffice.
I like your blog by the way, you seem to be going on a similar journey to me!
Created by Chris Cox on 02.12.2005 1:02 am
This is way off topic, but do you find that some of the best parts of a post are in the comments? I wish the comments were part of the RSS feed. Have you ever seen a feed that included the comments in the description body? I'm tempted to give it a shot.
Created by Ian Landsman on 02.12.2005 1:02 am
Compared to other processes, XP may seem like coding first. The real difference is that you move a lot of the planning and design to happen along the way, rather than all up front. (And when you design a piece of code, you're always taking the approach of doing the simplest thing possible to achieve that feature. no planning for "oh, but what if we need to plug in a new blah blah blah in a year?")
You're correct that automated tests will tell you if something is technically working. But, here's the kicker: let's say something's not working from a user perspective. You can have a lot more confidence in changing your code to match what the user wants if you have an automated test suite. If adding a feature ideally requires mutating code in 5 different places, that can be a risky proposition without automated tests. With them, it's a lot more reasonable.
While test-driven development has some nice advantages in terms of how you end up designing your code (because you're forced to make things nice and modular to make your tests manageable), it has the even bigger impact of letting you rapidly adjust to user requests without worrying as much about breaking things. (Automated tests do not, of course, eliminate the need for human testing... they just improve your chances that things will work when the code reaches the human testers.)
Created by Kevin Dangoor on 02.12.2005 1:02 am
Hmm. Interesting. I haven't read that much on XP but it sounds alot like what I actually do. I was under the impression that you code first with XP.
With rewriting large parts of code, I really mean when B doesn't turn out as you expected from a user perspective more so than just whether or not it in fact works. The automated tests I've used in the past and use currently let me know if something technically works the way I expect but not if it is actually a good user experience.
Created by Ian Landsman on 02.12.2005 1:02 am
XP does, in fact, require some "light planning and thinking". Basically, all of the function points are written up as "user stories". These have nowhere near the level of detail of a functional spec. They're considered "placeholders for a conversation" and have just enough detail to make a ballpark estimate as to how long it will take. If something will take longer than a week or two, you break it down into more stories.
The estimates are key, though. If you had originally been thinking about A, and now you have the idea for B, you need to estimate how long B will take. Then, if you want to do it, you need to put B into the schedule, consciously shoving other things aside.
If you're worried that B might not work out, maybe there's some "B lite" that you can try out to see if the idea makes sense. Estimate B lite, put that into the schedule and you've reduced your risk while still possibly being able to take advantage of a really cool new idea.
As far as rewriting large chunks of code goes: that's what the automated tests are all about. They're your safety net, and they allow you to change gears midstream with much lower risk.
Created by Kevin Dangoor on 02.12.2005 1:02 am
That's a great point. I think it's extremely important to capture the items you learn while building the system and implement changes base on that knowledge. The question is if A is what you had planned and now B would be better is it worth the time to do some light planning and thinking about B before jumping in?
There's many times I don't but would it be better to? I've definitely jumped in and come out with great stuff. On the other hand I've also jumped in and ended up going back and rewriting large chunks of code because it didn't work out as I thought it would.
Created by Ian Landsman on 02.12.2005 1:02 am
I've gotten the agile bug, myself. Before starting Blazing Things, I was worknig full-time in an extreme programming environment. I think that very detailed functional specs, written ahead of time, are a waste of time. There is so much learning that happens over the course of the project, that quite a bit of what is considered at the beginning is not likely to be optimum when you get to the end.
The tradeoff for not doing the big functional spec is a need for solid, automated testing and frequent attention to planning. The payoff is 1) working software faster, 2) end product that takes more advantage of the learning that happens throughout the project.
I've read that there are pockets of agile/XP experimentation going on within Microsoft. No one has done XP on an Excel kind of scale (that I've read about, at least), but I'm sure the techniques can be applied within teams.
Created by Kevin Dangoor on 02.12.2005 1:02 am
Yeah I agree, though having very little design skill I probably prefer the Joel method 
I'm am pretty good with UI and I do usually include some rough HTML mock ups in my outline.
I also have a feeling that a large part of the difference is the size of the organizations. Since SvN is 3-4 guys it's pretty easy to all be on the same page with ideas. If you need clarification you just ask. At Microsoft where working on the Excel team probably includes interactions with hundreds if not thousands of people, then a strong written document is really essential or you'd have to spend every minute in meetings just to communicate your ideas.
Created by Ian on 02.12.2005 1:02 am
Ian,
I would say they both have interesting points that conflict with each other, but can benefit us all.
I think 37signal's main idea is "It's the interface, stupid", which is true. If you leave it up to the developers, they will include every "cool" feature they can think of, and the app will grow out of control. Once you're done, you may end up with an interface that only a programmer could love. Time and time again (as we've seen with Ford, McDonalds, etc), without user adoption you are sunk in the water. A strong, intuitive interface also reduces the time needed for training your users which can help you deploy quicker.
On the other hand, Joel is right too. If you are developing an application for a client (hopefully not at fixed price), you need a very strong functional spec. I would go further to say that if you do not have a strong functional spec, you cannot give a true estimate of what it will take to develop the app in terms of time and money.
So in the end, I guess the ones that win are those who subscribe to both ideas 
...just my 2 cents...
Created by Liam Strand on 02.12.2005 1:02 am
Ian, I am in agreement with you that functional specs need to be done. They need to be kept tightly scoped, but they need to be done. More on my blog:
http://www.christopherhawkins.com/02-16-2005.htm#77
-----
Created by Christopher Hawkins on 02.12.2005 1:02 am