I 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