Agile Specs

Agile development methods typically don’t mention specifications as part if the process. You might hear things like user stories, but a specification typically is considered territory for waterfall methodology. This is really a shame because a spec is a great tool when writing software. A good spec can help clarify purpose, known limitations and define finite details that might be otherwise left undefined. These sorts of constraints help to define what the big picture really is for the software.

What makes a spec fit in well with agile practices is a reference implementation that is developed along side the spec. As your spec helps to define a larger design, the reference implementation helps keep the unknown details in focus. When you don’t have a reference implementation it opens the door for massive feature creep and design of features that are unnecessary. It is like trying to paint a picture with one big brush. It doesn’t work because you can only paint an enormous image with no real detail. The reference implementation provides an opportunity for detail, which means that while some system may become complex, it is still manageable because you have the big picture in the spec and an implementation that supports the design described by the spec.

My spec writing skills are not the best, but I’ve found it is worth it to try and design up front. Just as comments have been an essential tool for me to keep track of what I’m thinking when writing code, a short spec is helpful logically working through the details of the application. It also can generally morph from technical notes to documentation, which is always helpful. One way software is like art is that you can look at every day and still not grasp everything you see.

There are always small bugs or features that you may miss. A spec gives you a cheat sheet for better understanding code no matter what development method you use.