I talk a lot about how having a spec is a critical component of software development. But how do you know that your spec is good, and that it has been developed enough? Simply put, how do you distinguish between a good spec and a spec that is lacking?

This problem had confounded me for a good bit of time, because it’s hard to create a rule surrounding spec development. Since most developers (myself included) are also generally bad at developing good specs, it becomes even more difficult to create such a rule. However, I heard a great adage from someone recently that I thought summed up how developers can see specs nearly perfectly.

If it takes more than 15 minutes to determine what it is that you’re building, the spec wasn’t done properly.

Before we get into what I mean, I want to add this caveat: this is a generalization, designed to illustrate rather to inform. I don’t recommend people buy timers and set them to 15 minutes, and at 15:01 send the spec back to the product team. That’s not what the point here is.

The point here is that developers aren’t usually spec designers, at least not when it comes to the actual development. When code is being written, the spec should be settled. There should be some kind of wireframe or description of the functionality required. This need not be in an abstract requirements document; it simply needs to be able to communicate effectively to the developer what the person who wrote it wants.

Having a spec that is clear and able to quickly tell a developer what is wanted allows the developer to spend more time on other things that are important, like designing the backend, implementing the functionality, testing and the front-end artwork. These are the true tasks of developers. Additionally, having a clear spec from the beginning helps ensure that the finished product will more accurately meet the intentions of those requesting it. This makes for happy clients, internal or external.

In order to employ this rule, however, there is a caveat: the 15 minute rule applies only to determining what is being asked for. It does not apply to debate over architecture, design, implementation, artwork, or other aspects relating to implementing the spec. It relates only to debate over the spec itself. Also, in cases where the developer is called to assist in developing the spec, obviously the rule doesn’t apply.

Making the spec better is a critical component of making development work. This rule provides a baseline, and should help produce better specs and ultimately, better products.

Frustrated with your company’s development practices? You don't have to be! No matter what the issues are, they can be fixed. You can begin to shed light on these issues with my handy checklist. Plus, I'll help you with strategies to approach the issues at the organization level and "punch above your weight."

Great! We'll be updating you soon on best practices for your team!

Brandon Savage is the author of Mastering Object Oriented PHP and Practical Design Patterns in PHP