Flapping CootI have recently had to start writing a Functional Specification for a development project I hope to start working on soon. OK so what exactly is a Functional Specification?

Even though I have been a developer for many years now I haven’t had a great deal of experience with complete specifications. This meant that I had to go and do some background reading to find out a bit more about what exactly was involved. So I thought I would write a post to summarise my findings.

The idea of a Functional Specification is that you define the scope of the problem, design the program and describe exactly how things are supposed to work, in detail. This is meant to cover the program purely from the potential users point of view.

If you want to get into technical details of how the project is to be written then that sort of information would be provided in a second document called a Technical Specification.

The Head First Method

Most projects I have worked on in the past have just been based around a loose concept of what was required. You tend to get an email or a note asking for a certain feature be implemented. Then you jump into the code, head first, trying to make the changes that have been requested. The theory is the quicker you get started the quicker you will finish, although this is not always the case…

The most common flaw, from my point of view, is that you don’t always have a complete grasp of the issue before you get started. You start going down a particular route to make a specific change only to hit a problem which challenges some assumptions you made earlier. The real kicker here is that you now haven’t really got time to start from scratch again so you have to tweak the problem areas to get around this new issue. This leads to untidy and sometimes unreadable code which in turn becomes much harder to maintain when the next change is required.

This problem even gets exaggerated when you scale things up. If you take on a larger project with multiple developers then the chance of them going off in slightly different directions is greatly increased unless they know exactly how their part fits into the project as a whole.

Advantages Of A Functional Specification

The simple act of creating the complete specification helps clarify the whole project and should highlight any conflicting areas before any coding begins. This should allow code to written a little more concisely if you already have the whole project nailed down before you start.

That is not to say that there will not be something crop up during development. No matter how hard you plan something there is always the possibility that something can get overlooked and a problem may suddenly appear. Chances are though that this will happen a lot less than if you just jumped in head first.

During my research I came across a very useful, 4 part, series of posts by Joel Spolsky titled Painless Functional Specifications. This link is to the first post in the series which covers why you need a spec. There is a pretty good example in there as well some details of the possible benefits.

Joel suggests that any project that is likely to take over a week or involves more than one programmer should have a spec. I would go one further and suggest that any project, however small, should have at least a basic written spec. You don’t need to go into quite as much detail as with a larger project but I have found from personal experience that small projects tend to suffer the same fate.

I have had a few personal weekend project that I started on a whim only to get a fair way into the project before I noticed the fault in my thinking. The choice then is either fix the problem or start all over again, neither of which is very appealing for something that was supposed to be completed in next to no time. So these projects tend to get abandoned…

The second post in the series, What’s a spec?, explains what should and shouldn’t be in the specifications. It also explains the difference between Functional and Technical Specifications. The third post is about who should write the specifications but it seems to be aimed at a large corporate environment so I’d skip that one. Then the last post contains some Tips on actually creating the spec.

How To Create A Simple Specification

So what have I learned? I think the most important thing is you have to realise that other people will have to read the document once you have finished. This means it should be as straightforward as possible with easy to follow examples to help the readers understand what you are trying to describe.

You should start off with an overview of the project. Explain what the project is supposed to achieve, as well as anything that is to be excluded. This will help stop any feature creep. Try and keep this fairly brief as it helps ease the reader into the document as well as giving a general idea of what the document is about. You don’t want someone to have to read pages of detailed information only to find out that the document is not the one they wanted.

Next up you need to go into detail of all aspects of the project. Describe the process and layout of each screen in detail using pictures or flow diagrams as appropriate—a picture is worth 1000 words after all. This is the most important section and so you must really concentrate while writing this and go into as much detail as possible. This should help you see how all the sections link together and so help you pinpoint any possible sticking points. At the same time through try and keep things concise otherwise the document can get big very quickly. You do not want people ignoring you hard work after all…

If you are a developer then you must remember that this is from the users perspective so there is no need to go into detail about the proposed database structure or how you plan to implement any of the functionality, in fact that will only be a hindrance. Those sort of details will add bloat as well as confusion to non-developers that read the document.

Image: Pete O’Shea

4 comments

Andy Ludgate

from the oar man,

excellent blog – silly boy
now I’m going to expect so much more from the spec.

Seriously though – good thoughts. It may rub off on me one day…

Andy

    Pete O'Shea

    Thanks Andy,

    It’s good to know someone else got something useful from this post. I’m beginning to see why people skip the spec as they certainly do take a bit of writing…

    Pete

Michael Ludgate

Nice post, whomever works on your project is sure to be thankful of a clear functional spec.

If you don’t have a functional spec likely there’s little or no documentation. No documentation means conversations, thoughts, intentions, dreams. Developers notepads with different and isolated understanding. Customers who said x, but meant y. And… testers/QA bashing their head against a brick wall. ‘Needs to be tested by tomorrow, we don’t know how it works, what the customer actually wanted, and if you think something’s wrong – it might be intentional.’

Functional specifications are important for all project stakeholders, it forms the introduction point to a project, providing a frame of reference for everyone who isn’t part of the developer water cooler group.

Without a spec, an analysts client meeting should be conducted by a salesman instead, they’re generally more skilled at filling in the blanks that having nothing written down leads to.

–“The spec is shown to the customer, who says “wait a minute! We don’t want to switch everyone at once!” So Mr. Rogers thinks some more, and amends the spec to say:

A document that doesn’t exist can’t be improved, you’re assuming you’ll take the best approach and cover all bases, but worse, your relying on the customer to communicate their requirements in one hit, without providing the opportunity to realise potential issues.

Testing without specifications, feels like Sudoku with a completely empty partially drawn grid.

–If you’re a software development manager and the people who are supposed to be writing specs aren’t, send them off for one of those two week creative writing classes in the mountains.

Urm, what’s a functional spec…

    Pete O'Shea

    Michael,

    Specifications are one of those steps that get left out so much that you almost forget they are supposed to happen. When you are in the learning stages of development this can make you feel like you are going around in circles as you tweak the job to match your view on how to glue things together. This in turn leads to many faulty decisions that could have been avoided if the whole project was tied down beforehand.

    I wish I had had some complete specs while learning a programming language as you can then focus on learning the language rather than juggling that with the glueing the parts of a project together at the same time. I’m sure it would give you a lot more confidence in your abilities from the outset.

    Thanks,
    Pete

Leave a reply