Friday, December 02, 2005

On Writing Specs

[This post is reproduced from a previous blog of mine, originally published August 20, 2005. I'm moving it here for good measure.]

I recently re-read Joel Spolsky's series on Painless Functional Specifications. It's a few years old now, but is still a pleasant reminder of what I think are the best reasons to write specs:

  1. Writing a spec forces us to think about what the software does. We have the opportunity to declare what the software does, how it does it, and why it does it. Should we need to change the design, it is preferable to do so up front, while we're spending cycles thinking about these things. Why? Because changing the design before construction begins is much less expensive than changing actual code, whether it be during the construction of the product, during testing, or after release. The easiest, cheapest, and certainly funnest time to fix design errors is before we've spent time and money constructing software based on a faulty idea of what the product does.
  2. Writing a spec provides us with a means of communicating about and refining what the product should be. We can share this document with product management, development, quality assurance, and even marketing. With input from all of the above, we can come to an agreement that the software described in the specification is indeed something that is, all at once, a) useful to the intended users, b) saleable to the intended users, c) can feasibly be constructed, and d) is testable. In order to satisfy these goals we can discuss the spec and adjust it accordingly. Change and compromise are expected.
  3. Writing a spec gives us a recorded document from which we can derive a list of things to do while we construct the product. We could attach dates to the items in that list, do some resource balancing and call it a schedule, if we're the sort who create schedules. Managing software construction and testing tends to be much easier to do when we have a list of tasks that need to be completed in order to deliver the product.

I realize that not everybody believes in doing some or all "design" work up front, but my experience tells me that every project of any complexity needs some sort of spec before the construction work starts in earnest. Call it what you will and record it in whatever form you wish, but do yourself the favor of writing a functional specification.