Painless Functional Specs Part 1
This Joel article came out after the Joel Test. One of the aspects of the Joel Test is having a spec. Apparently, Joel got some pushback on that so he launched into a series of articles on Painless Functional Specs. This is the first.
A Product of It’s Time
When I reviewed the Joel test I also pushed back on this assertion. My take came at this from more of an agile perspective. In Joel’s defense, this article was written in October 2000 and the Agile Manifesto was not written until Feb 2001, so it wasn’t codified yet. Even though the manifesto hadn’t yet been formalized, the undercurrents were still there. The Agile movement was this rebellion against corporate process overkill. Specifically planning and documentation were targets of this rebellion. See the bolded portions of the Manifesto below.
We are uncovering better ways of developing
Agile Manifesto
software by doing it and helping others do it.
Through this work we have come to value:
Individuals and interactions over processes and tools
Working software over comprehensive documentation
Customer collaboration over contract negotiation
Responding to change over following a plan
That is, while there is value in the items on
the right, we value the items on the left more.
All or Nothing is a False Choice
Some adherents of Agile tend to disregard the last statement in the manifesto. They completely ignore the items on the right. I think that is where a lot of Joel’s pushback came from – people who thought that the cure to too much process and documentation was no process and documentation.
In his example, Joel cites Speedy and Mr. Rogers. Speedy does no specs upfront and just disappears and reappears a few weeks later with the solution. Mr. Rogers refuses to do anything until the specs are done. He takes the time to talk to all the stakeholders and gets their input first and then designs the perfect solution upfront before writing any code. Speedy manages to get everything all wrong, while Mr. Rogers saves the day. Of course, as you can imagine based on the title Joel is a fan of Mr. Rogers and not Speedy. Joel makes it seem like those are the only 2 options. This is a false choice. There is a middle ground.
It is possible to generate just enough of a spec upfront to get a good idea of what the project is about. The Inception Deck by Jonathan Rasmusson is a good place to start. Once you have an initial idea, that is all you need to get started. Then you can keep iterating and improving the code. The initial spec can be improved as you and the customer learn more about the problem.
One thing Joel did get right is Mr.Rogers does go back and talk with the customer and his boss. I think that is good, but iterating on the spec is not the same as iterating on the code. It lacks context. As you build the code you learn more about the system and as the user uses the system they also learn more about exactly what they want the system to do. Iterating on the specs upfront misses out on all that learning.
Words Are Easier to Change Than Code
The first reason Joel cites in favor of specs is that words are easier to change than code. Editing the requirements doc is easier than rewriting a bunch of code. There is some truth in that. It’s well known that the later in the process a problem is caught, the harder it is to fix. Too many things are built upon it and people become too attached and don’t want to throw things away.
The solution to this is not big design upfront. The solution is to take smaller steps and get quicker feedback. Quicker feedback ensures we catch problems early before anything else gets built on top of them. Taking smaller steps makes it easier to throw code away. Throwing away a couple of days’ worth of work is hard. Throwing away 5 minutes’ worth of work is easy. Another thing that helps with this is getting really good at refactoring. Then you don’t need to worry upfront about making your design extensible and accounting for all the possibilities, you can add that flexibility easily just in time, as you need it. If you discover you don’t need it, then you haven’t wasted any time implementing and you haven’t overcomplicated your code for no reason.
Specs Save Time Communicating
The second reason Joel cites in favor of writing specs upfront is that it saves time communicating. He makes the claim that a detailed spec allows you to communicate things once upfront. I agree with the importance of communication and making sure everyone is on the same page. For that though, I prefer the inception deck. I think it does a much better job than any of the requirements gathering processes I have seen.
Getting everyone on the same page at the beginning is only part of the problem. Communication is not a one-time thing. It should be continuous. Saving time by only communicating things once upfront is misguided. There will be questions, and your understanding of the problem will change. Joel’s objection comes from a siloed world where QA people are interrupting developers with their questions. He’s promoting a world where developers just disappear and magically show back up with the right answers at the end. Apparently, at that time, cross-functional teams weren’t a big thing. With a cross-functional team, the QA guy is not interrupting the developer because they are working together, side by side, on the same problem. Joel’s reasoning here only applies if you are stuck in a siloed, waterfall world.
Specs make schedules possible
Joel’s last argument in favor of upfront specs is that they make scheduling possible. Joel asks, “How can a responsible business decide whether to build a product without knowing how long it will take?” In order to come up with a timetable, you have to know all the features you plan on implementing. This is steeped in waterfall thinking. It lives in several illusions. The first is that we can know upfront all the features that we want and the second is that we can know ahead of time exactly how long they’ll each take to implement. A schedule bears no resemblance to reality. It is an estimate. Nothing more than a best guess. It is likely wrong. Also setting a fixed date has zero flexibility to make any changes as you learn more about the problem. Basing business decisions on a schedule is insanity.
Instead, turn the premise upside down. Forget the waterfall idea that you need to deliver everything at once (at the end) or the project is a failure. Start thinking incrementally. If you have a fixed budget to spend, how many iterations will that pay for? And how much can you get done in an iteration? If you don’t know the answer to that question start iterating and observe what happens. Pretty quickly you’ll realize if your idea is feasible and you’ll have a good (but not exact) idea of how long it will take. Instead of basing business decisions on some predetermined date that has no basis in reality, base them on actual data gathered by actually doing the work.
