Specifications - Part of a Complete Project

Many of us with computer-oriented vocations aren't to happy about the prospect of writing things down, especially on paper. Sadly, language is one of the greatest accomplishments of our race for a good reason. A little writing can help a lot when it comes to a project, and can easily change the outcome by hours, days, or weeks, as well as create better code/configurations in the end.

Writing a technical specification is necessary for any project that will take more than half a day to implement. There is just no substitute for taking your idea and fleshing out the details and putting it in writing before you even touch the code. There is something about writing it down that makes those great ideas look meager on the page (or screen as it may be), and that isn't entirely due to the chicken-scratch you call handwriting (or finger prints). This initial planning helps because you're able to see how that first step will integrate into the tenth step while you're doing it so that you don't have to go back and re-mold it later. You also have concrete goals so you know what that tenth step actually will be!

This post was inspired by Joel's Painless Software Specifications. If you haven't read those four essays, go read them--now.

Specifications apply to almost anything you do, from setting up a new system to adding a new service to writing a server script to writing client applications. Even if you're the only who will see it isn't just a good habit, but it will improve the quality of your code, reduce the time it takes to debug, and probably speed things up in the end.

Before I wrote specifications for everything, 90% of my projects would stall at the actual implementation. Setting up that VPN was easy, figuring out how people are actually going to get certificates, log in, and use it is another matter and would often get delayed for weeks because none of the users really knew what they wanted either.

In short, write your specs and good ones. They save time in the long run.