Mark Panay, co-founder of SimpleWeb, shares some thoughts about what should be in a spec.

We receive a lot of ideas for applications, both mobile and web-based. Sometimes we get the most amazingly detailed documents that give us a thorough understanding of what the idea is and what it’s supposed to achieve. Sometimes…!

Mostly, people do know what they want, but don’t often know how to describe their idea and miss out large chunks of information, assuming that whoever they are talking to knows the context. It’s easy to do, especially with a complex idea that they’ve been thinking about for some time.

When we get job referrals like this, we ask the client – at the expense of possibly losing the project –  to clarify their idea using two specific approaches. This also helps us to determine whether the potential client is serious about the project. These approaches are:

What is the essence of the idea? This is essentially the ‘elevator pitch’ –  one minute to pitch the idea to a customer or investor
Simple user stories. Who are the various users in the system and what are they able to do within a defined set of areas?

We also ask for a simple overview summary, which is always useful, like a longer elevator pitch.

The essence
You’re trapped for 30 seconds in an elevator with your dream client (or investor) and you need to explain what your product does. This is the number one stumbling block: what is it that makes your product special?

Good: “We’re building a product that makes it really easy for people to change TV channels without moving from their couch.”

Bad: “We’re building a small plastic device that has various buttons including a volume control and channel controls, that via infra-red allows the viewer of a TV to change various parameters on their TV remotely.”

The former is succinct, has context and gets over the idea. It’s not technical – just the essence of the product. If a client briefed a developer like this, it would get built. It might be pink, have 12 buttons, take 5 AA batteries and work by using sonar but you would get a product that achieves your business requirement.

It’s much easier said than done though. You need to test your pitch on as many people as possible.

Simple user stories
User stories are a pragmatic way to ensure a project is communicated effectively. Essentially we want the client to describe the application for particular types of user, without telling the developer how to do it. This means clients don’t have to keep asking: “is it possible?”; they just state what is needed. The developer then needs to figure out how to prioritise and achieve these requirements within the resource available.

There are many ways to obtain a set of user stories. We like the MoSCoW ( method. A client starts with a list of what they want to be able to achieve functionally, with simple priorities based on MUST, SHOULD, COULD or WON’T. For example, a user:

SHOULD be able to sign up to an RSS feed MUST be able to sign up to a newsletter
SHOULD be able to post comments
MUST have a public profile
COULD submit an idea to improve the website
 WON’T be able delete a roller without a warning.

The idea is not to describe how to do something, only what you want to achieve.

You will find that a lot of your requirements are generic, in that a lot of other applications already offer the required functionality, such as registering, logging in, profiles, etc. This is where your research (and you’ve done your research, right?) will play a big part. You can model them quite quickly using the MoSCoW method, leaving you just to map out ‘the essence’ as MUST, SHOULD, COULD or WON’T.

 You could separate these features out under two headings, Generic and Essence. In the generic section you could be less granular and focus all of your energy on the features that make up the essence, as this is the part that makes your product special.

Essentially the aim is to give the developer as much information as possible as early as possible. Oh, and one more thing… make sure you allow your developer enough time.

Follow Mark @