Authored by Primate

A rather awesome, informative
and witty blog about all things web

Why You Should Write Specifications For Web Projects

Fingers pointing to a map

With the appropriate specification, only one finger would've been necessary

A few months ago we asked if you actually bother to write specifications for your web projects. In that article, the main argument against them was that it’s a dead document, nobody cares about it in the end and that the main focus should instead be in working with clients to meet their expectations. Well, it’s now a few months later and I think we should try to defend technical specs a little.

Define “spec”

I think everyone would agree that a lifetime of hours and metric tons of paper have been wasted on writing and printing functional specs over the entire history of programming. Perhaps then some would argue that the single most positive result of it all is a lesson that we should just simply stop doing them. I disagree, however, and strongly believe that the majority of web projects require some sort of specification and thus the rest of this article will refer to the following definition: a software specification is the attempt to create a level of communication, common to all parties involved, which describes the vision of the project and the limitations in technology, time or budget, which eventually form the scope of the overall job. It should clearly define the deliverables and be accessible to everyone involved at all times.


A key aspect of spec is to get groups of people who all have different perspectives on the project to talk to each other and appreciate everyone else’s point of view. It is very important to make sure everyone is aware that creating a spec is not only a difficult and emotional part of the process but also plays a significant role in laying down the rules for its duration and future.

It is the time of the strongest tensions.

Clients try to get as much for their money as they can and very often they get annoyed when facing the reality of not having enough cash to make their great visions come true. Developers have tantrums, crying that these ideas are impossible to deliver and it’s too much to do in not enough time. Project managers are stressing out trying to calm everyone around down, digging their own graves by giving out mutually exclusive promises that are impossible to keep.

Yet despite all the drama, it is a time when decision makers on all axis of the project should work together to define the priorities. Clients should state key business requirements, developers should highlight areas of technical uncertainty and difficulty and project managers should seek the best suited solutions within the given time and budget. But most importantly, it is also the time when people should try to understand each other.

The client’s perspective

From the clients point of view, being involved in creating a spec should be very beneficial. Very often clients come in with a very clear vision of what they want to achieve (or at least they think so) and by participating in spec creation they can discover potential new solutions and can often be inspired by possibilities they didn’t even realise existed. Confronted with people who have radically different takes on the project, clients can actually learn a lot about their business processes, reflect on their day-to-day operations and get excited by future potentials by simple allowing a little bit of healthy discussion.

Project managers are stressing out trying to calm everyone around down, digging their own graves by giving out mutually exclusive promises that are impossible to keep.

The developer’s perspective

For developers the creation of a spec is the perfect time to understand the entire project and its priorities. It’s the time to ask the right questions and think of potential solutions, the time to highlight areas that are technically challenging and those that will be easy to deliver. Teams of developers could be perfectly suited to best gauge the timescales needed to deliver each individual component of the project and, in which case, they should better be left alone for über-geeky, fierce discussions that nobody else would make any sense out of anyway. When involved in the process of creating specs, developers become valuable resource as they are the people who will transform the ideas from paper into working code.

The project manager’s perspective

From the project manager point of view, having a spec should be equally important. It should be a reference point for updates in timescales, budget and scope. The dynamic nature of a project spec is its natural characteristic and should always change in context of money, time and manpower. For PMs, specs are the tool of negotiation with the client when scope and requirements start to creep out of control or timescales become squeezed. They are also a great measure of team performance and reference for review. When done right, a spec becomes a progress bar and tool for comparing how initial time estimates relate to actual deliveries, allowing early corrections in the project’s calendar and putting project managers back in control.

How to write a good spec

Probably the most important characteristic of a specification is its accessibility. Specs should be understandable by everyone involved, especially the client, and this is probably where functional and technical specs fail the most. Accessibility also means that specs should be available to view by all parties at all times and there should be an easy way of proposing and discussing changes to them.

Of course, specs that try to describe what the user will be able to see and do at every step is not always the best idea. Writing a spec for the front-end of a web system is an extremely boring process and an equally boring read. Probably a much better idea is to write specs in the form of short scenarios of what each user will be able to do and then back them up with story boards and mock-ups.

This combination of storyboards (design mock-ups) and scenarios allows all parties to bring up key elements of the project and its important technical aspects. They give an instant visual reference and explain the behaviour in a way that makes it easier for clients to articulate their expectations, for developers to understand the business priorities and for project managers to control the process in a more conscious way. To help with there there are many online tools like Basecamp, Trello or Pivotal Tracker, all them supposed to make this communication easier. Which one to pick (if any) is tough a decision but one you should most likely use one to get everyone involved and let them speak to each other.


Ultimately, specifications are tools that bring clarity to projects by providing a focal point for discussion and the exchange of ideas. They are not only a plan for the implementation of technical features and a way to document change and measure success but also an opportunity for clients, developers, designers and projects managers to come together at a single point in time and collaborate on creating the most appropriate (and best) product possible. Without a good spec, not only would it be difficult to actually contain the scope of the project but it’s likely that all parties involved would each be visualising different solutions to different problems.

Image credit: Johannes Lundberg

If you liked this article then why not subscribe to our RSS feed.

Author: Bart Oleszczyk

Bart is a man of few words and occasional long blog posts.



Showing One Comment

Leave a comment
  1. Leanspecs Blog February 21, 2013 at 10:00 pm

    [...] Eyes on the goal – A clear, complete specifications allows you to see the goal and know when you’ll reach it. It’s easy to get lost trying to make each of individual part of a product the best it can be. Agreeing ahead of time of what is “good enough” can help you avoid falling into the trap of trying to achieve perfection. While individual specifications may change, the overall scope shouldn’t – driving you to release a product faster and avoid feature creep by over developing parts of the project. “Probably the most important characteristic of a specification is its accessibility. Specs should be understandable by everyone involved, especially the client, and this is probably where functional and technical specs fail the most.” Why You Should Write Specifications [...]

Leave a Reply