Joel Spolsky Speaks Specs

Joel Sposky (Joel Spolsky)

It seems that specs are like flossing: everybody knows they should be writing them, but nobody does.

Another for the wish I had said that list. Joel Spolsky wrote a four part series on writing functional specifications in Oct 2000. Joel’s opening position is that all projects lasting more than a week, or with more than one developer, will be completed faster with specs than without them. He presents three giant reasons to use a requirements document as part of developing software

Three Giant Reasons

Here are our thoughts on his reasons

  1. Iterations are faster when changing requirements than when changing code.
  2. Communication is more efficient when using a document.
  3. Planning without a plan is impossible.

Faster Iterations

Function requirements documents provide a lot of information. The FRS is much less verbose than code. Code has precise implementations to support every detailed contingency of what the application should do.

When we challenge our requirements, in addition to uncovering overlooked requirements we have an opportunity to improve the requirements we do have. These are bug-fixes in the requirements. Each requirements update is pushed to the developers, ideally with a way for the developer to quickly assess what has changed, while ignoring what has gone before.

Efficient Communication

Without a spec, every discussion about the software being developed happens between two people. And many discussions happen multiple times. 100 one hour conversations about the desired functionality in the software will cost us 200 hours without a functional specification.

With a functional requirements specification (FRS), we might invest 10 hrs creating the document. The 100 conversations are mostly replaced with 100 “lookups” into the FRS. Even if those lookups each take an hour, we’ve saved 45%. The savings comes because the developer (or other expert) only has to talk once – when providing data to be used in the requirements.


We plan software releases, typically with timeboxes that allow us to scope what is in and not in each release. In feature-driven developement (FDD), the idea is to create a high level plan for the whole solution, and a detailed plan only for the current release cycle. This incremental delivery approach is more efficient for creating plans by preventing reworking of detailed future plans.

The level of detail to which we can reasonably plan a release is inversely proportional to the amount of time between now and the start of the release. Even if we have mastered PERT estimation, and document how we created our estimates, the plan will still need to be reworked. This rework doesn’t come from refining our estimates, it comes from changing our requirements.


We create specs because they save us time and money on all but the smallest of projects.

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.