On Specifications


An act of identifying something precisely or of stating a precise requirement

Specifications are a way of laying out client requirements, maybe in slightly more depth, or more technical detail than used in user stories.

It’s important to know exactly where the limits of a feature need to be, and what functionality the client expects. These explicit declarations are needed for all aspects of the development cycle, from project managing (accurate time scales can’t be given if people have to keep going back and changing things) through to testing – we need to know exactly what data to test the functions with, what the expected results and goals are, and how it integrates with other parts of the system.

The specification template I use is as follows:-


The user story/ies associated with the feature, or a short description of the feature


A more in depth, numbered and/or bulleted list of every part of the feature. Multiple lists can be used if different users will interact differently with the feature (for example, users and admins, or clients and the users/customers* of the site). These should also be in priority order.

This can also include use cases, and what to expect when using it, thus forming part and a good basis of a test plan. It’s also important to include what the specification or feature doesn’t cover – what’s out of scope or needs to remain unaffected by the new feature.


To be filled in after development is finished. This is technically not part of the specification, but is useful when the feature is to be put on other sites. It specifies any modules used, or things that need to be installed in order for the function to work, any information needed from the client, and any dependencies that the feature has.

This document then serves as a specification and a useful document for training clients and staff in how to use the feature. Its a central repository of all the information about this feature, and so prevents the situation where only two people understand how a feature works, and the panic that can occur when those people are off work, or move on to another job.

Efficiency is the name of the game, here. Testing takes up a lot of time, and we don’t directly generate money for the business (not directly anyway, not in the same way developers, designers, and support staff do), so working quickly, but efficiently and effectively is even more important than you first think.

A specification is pretty much the most important document you can have when it comes to development and testing. Without it, you’re left developing and testing something based off notes, emails, or maybe even a remembered conversation. Now, you could argue that there are some features that are small and simple enough that a full specification isn’t needed, but I still believe that a document – even if it’s just in that specific client’s file of folder, that explains what the feature is and how its used is useful for future reference.

*In my current job, because we are an e-commerce company, we refer to clients and customers as a way to differentiate our clients, who run and use the site, and customers, who buy things from our client using our sites. In other environments, users could work in the place of customers.