The Importance of the Functional Specification


Warning: Illegal string offset 'filter' in /var/sites/t/theproactiveprogrammer.com/public_html/wp-includes/taxonomy.php on line 1409

Functional specifications are important. We all know this, or at least we all acknowledge that we are supposed to think they are important. We are supposed to always write one, or if someone else is doing the writing then we are supposed to always read it. However, we also know how things often happen in practice. Sometimes no-one bothers writing a functional spec. We might get our heads together in a meeting and brainstorm a feature or product, or even better draw some sketches on a white board, but do we really need to bother with an official spec? These are the days of the agile team, and sitting down to write a long formal document doesn’t feel very agile. Wouldn’t it make more sense to just communicate frequently and refactor? Make decisions on the fly and demonstrate to users often, iterate and so on? After all, the agile manifesto itself declares “working software over comprehensive documentation”.

In theory (ironically) this more “practical” approach sounds like it should work. However, teams that work in this way are really missing the point and avoiding some harsh truths. The theory goes that it is pointless spending much time up front writing out a big and detailed specification, because once we get going we will find out that for one reason or another our original spec was wrong. Once we know more we realise that there is a better way of doing things. What people fail to realise, and more tragically fail to act upon, is the fact that functional specifications should be ever-changing documents. They should be as dynamic as the codebase itself. This key fact has been largely forgotten in the software development community. Why? Because often no-one wants to take the responsibility for writing the document in the first place and then keeping it up to date.

Which brings us to another relevant question. Who should actually write the functional spec? Should it be a lead developer or a “business” member of staff? I personally don’t think this matters too much, as long as it is someone who is capable of writing to a reasonable standard, who understands what the team is trying to achieve through communicating with the client, and who is prepared to constantly update the document and take full ownership of it.

But what is the point of this document? If the team are all communicating well with each other and the client, then why bother writing everything down? There are two crucial reasons which I feel are often overlooked when it comes to discussing the benefits of a functional specification. The first is this:

The best way to explore and clarify a vision is to write it down.

This applies to all areas of life, and is a fact which has been reinforced through experience in my own life time and time again. It is the reason why us humans keep journals, write mission statements, write down our goals and make to-do lists. The power of the written word extends far beyond books. You can discuss ideas all you want, but the moment you start committing those ideas to words, your mind will open to new things which you hadn’t thought of. This is particularly true of the stereotypical programmer, who is more of an introvert, and experiences more moments of creativity during times of solitude than in meetings. It is of course true that group brainstorming sessions are useful, and these are still an important part of the requirements capture process, but the next step should be to write things down, in detail.

The second key reason why functional specifications are important is this:

Making lots of decisions on the fly results in decision fatigue.

Decision fatigue is a term I had not heard of until relatively recently, but as soon as I started to read about it I realised what a huge problem this was in modern life, let alone software development. Our mental and physical resources are limited, yet we want to achieve goals which require significant energy, so we need to do what we can to get our work done in an efficient maner. If we settle for a vague description of what we are trying to achieve, and then start working on it, we will find that we are constantly having to stop and think in order to make a decision. Should this button go on the left or the right of the screen? Should this be a radio button or a drop down list? What should this automatic email say exactly? The time for making decisions like this is during the writing of the functional specification. These are the details which we become aware of as we write, and in order to write a complete spec, we need to make those decisions. If we wait until halfway through a sprint, then the developer will have to either make a decision themselves based on their own opinions, or approach someone else to ask for their opinion. Either way, someone is making a decision impulsively, and who knows when that decision will be considered by others, if it ever will. Small issues like these accumulate to produce a solution which lacks consistency and quality. A better approach is for the person who is writing the spec to make a decision, whilst her head is in that space, and then circulate the document to everyone to read over, and let the feedback loop weed out any decisions which could be improved upon.

The end result of this process is a project where developers can get on with doing what they are good at and what they want to focus on – writing code. Not deciding upon functional requirements or content. There is a lot to be said for allowing professionals to focus on one thing at a time. Of course, in the modern landscape we do need a range of skills, technical and soft, and we do need to remain agile and flexible. However, it is equally important that we work intelligently so that we can wear one hat at a time, gather similar tasks together so we can focus and gain momentum, and avoid wasting time and energy. Acknowledging the importance of a functional specification is a good start.

If you are interested in this topic I would urge you to read the excellent series “Painless Functional Specifications” by Joel Spolsky.

Share Button