Sunday, February 05, 2006

Meticulous Specification

Like most programmers I disliked long specifications. I didn't like reading them, and more importantly I didn't like writing them. For me, all of this has changed, and I believe that this is a positive change.

In my line of work we typically deal with fairly small projects. These are fairly easy to estimate, and more often than not we are being paid by the hour, and not by the job. Recently we were implementing a specification that weighed in at almost 200 pages, a project much larger than we usually deal with, and unlike most of our projects it required a fixed price. On top of this we needed to put a price on it with only a few days of review.

What happened is that we later found that the specification had much in the way of ambiguity, holes, and errors. On one page it made a statement just to be reversed in another part of the document. There were also many changes that were required by both the designers on the client's end, and the engineers on ours while the product was being developed. Basically we had rushed to start work, but never really had a solid specification to build from.
Building a large system without a specification is impossible, building a large system with a poorly written specification is even harder.
This same project had a second part to it, and I was convinced that we could do better. I spent a little over a week reviewing the specification of just my part of the larger project. I held several sessions with the client to review the specification, remove ambiguity, and document any items missing from the specification. This also included updating the specification for client review and approval.

In the end I was able to submit a task list to the project's manager, and a good estimate of how many hours each item would take to complete. I am now fully aware of what I need to build, and because system is well documented, I could pass off work to other programmers without having to explain too much. I am also seeing that the client is a little more confident of the outcome because they know exactly what to expect in the way of deliverables and schedule.

From this experience I have formed a few simple rules that will guide my work on larger projects.
1. Review the specification, and resolve ALL questions before any coding begins.
Having your questions answered before implementing an incomplete specification will ensure that you only code what the client needs and not those things that were incorrectly stated. Nothing is worse than finding out late in the game that a client decided to not build in a feature, but forgot to remove it from the specification.
2. Review the design, and verify that ALL of the content and links are documented before any coding begins.
If you look at the design, and you aren't sure where a piece of content comes from, then the client might not know either. Get these issues resolved before coding begins, because not fully understanding where data comes from will usually create more work for you.
3. Update the specification as you receive clarifications from the client, and get approval on the changes before any coding begins.
Make the client take the time to review and approve the changes to the specification. This gives them one last opportunity to catch any problems with the specification. Once approved you can be pretty sure that the specification will stand on it's own two feet.
4. List all of the tasks that will be required to implement the specification, if any task is more than 8 hours worth of work, break the task into smaller pieces.
If you completed the first three steps, creating a valid task list is fairly trivial. If you find that you can't put a number of hours on a task, or if your "tasks" are specified in days and not in hours, then you probably need to revisit the first three steps and try again. A comprehensive review of the specification will give you the confidence in your estimates and task list because you will know exactly what you need to build.

When done properly, a meticulous specification review can save you both time and frustration.

No comments: