Articles

Writing specifications for web applications

Specifications are an integral part of any web project (or any software project for that matter). Writing good specifications will improve the probability of success for a given project by a great deal.

Why spec?

Specifications encapsulate a project's goals, requirements, features and scope. This is very important for several reasons:

Understanding project requirements

Understanding what a project sets out to achieve might seem obvious, but in reality, when at least two people are involved - some difference in perception of the project goals and needs is inevitable. Putting in writing the goals and requirements goes a long way towards resolving such differences.

Writing specifications will often reveal requirements not thought of initially, as a result of detailing and thinking through the initial set of requirements. This is very important for determining project scope.

Developing a project scope

The scope of a project is probably the single most important attribute for determining project success. A well defined scope will determine the time-frame, costs and requirements with good precision.

In essence, a scope is the sum of a project features, requirements and deliverables or in other words - the sum of the work required for project completion.

Scope is the main element against which projects are priced at Lionite.

The more complicated and/or innovative a project is, the more likely it is that features will change during the project lifetime (sometimes even drastically).

We can allow that to happen by adhering to scope instead of individual features. With good specifications it is much easier to avoid scope-creep.

Estimating project time-frame and pricing

Accurate time and cost estimates are important are as important to project success as anything else, and specifications are what it should be based on.

The better the written specifications are, the more accurate those estimates would be.

Creating a workable reference for development and design

Working with a good specifications document can do wonders for productivity and focus in the design and development stages. At the very least it can serve as a task list for project completion.

Well thought through description of features and relevant mockups can solve a lot of potential dillemas for both designers and developers and save a lot of time.

The specifications process itself should be used for ironing out as many issues as possible, helping the implementation phase to be as productive as possible.

Having a standard to test against project delivery

Specifications outline the agreement between parties on what constitutes a successful project delivery. Contracts, if relevant, will point to the specifications as the legally binding document for this purpose.

A good specifications document can resolve many potential disputes simply by stating clearly what should be delivered.

How to create better specifications

Creating good specifications entails some ground work, there's no around it. Keep in mind the effort you put in will pay itself back as the project progresses.

Break everything down

Decompose every requirement and feature to a list of small tasks. Add relevant detail that might affect completion time. The level of detail and scope of each task should be enough so that it could be accurately estimated in work hours (and not days, and certainly not weeks).

Research what you are not sufficiently familiar with. This will greatly help avoid nasty surprises later, and will make your estimates that much more accurate.

Be thorough

Try to make sure there are no gaping holes in the specifications - are all requirements and features accounted for? are there any hidden prerequisites you might have over-looked? read everything twice and then give it to a colleague to read.

Don't forget to add more technical detail such as security concerns, coding standards, post-project technical support and supported browsers.

Compose interactively with clients

It is very important for the specifications to capture correctly the vision the client has for the project. Specifications writing can be used to correctly align client's expectations with your own.

Your interaction with the client can (and probably will) lead to more insights on project requirements and features. It is not at all uncommon for a project to change direction somewhat during specifications writing - and it is much better that it happens at that time than at mid-project.

Be clear and concise

Be clear and and use as much detail as necessary. Be concise, since overly descriptive texts are harder to consume and understand.

Don't skimp on rewording and reorganizing bulky / technical paragraphs and edit out unnecessary detail.

Read more articles like this one

Joel Spolsky on painless functional specifications - part 1, part 2
Allen Smith on functional specifications
Jason Fried of 37Signals on avoiding functional specifications (basically refuting everything I've written here. A good read for counter arguments.)


Back to articles This article was originally published in techfounder on Jul 3, 2009