A Good Functional Specification

Functional Specifications are the bane and salvation of every developer that has come across them. They are a detailed document on how users or 3rd party actors will use a system. Developers loathe these documents when they read like a bad novel, disorganised and difficult to separate into different use cases or functional parts. A good functional specification is a great reference on how the user will experience the application. It’s a document that helps keep all the stake holders on track and communicating effectively. It’s a solid foot hold for creating technical specifications, documentation and testing guides.

Living Document

Most people assume that a functional specification gets written at the beginning of a project and never changes afterwards. A good functional specification changes during the course of a project. The assumptions and conditions at the start of a project never stay the same until the end. A functional specification should reflect that, updating and keeping records of the updates as the project matures. This way it becomes a great document for reflection at the end of the project.


The introduction of a function specification should start by stating the problem that the document addresses, It’s the story of the project commissioner. The introduction should state who all the key stake holders are in the project. This help any future work or investigation to pinpoint reliable sources of information. The introduction should list and describe the terms being used in the project and document for clear communication.

Out of Scope

This is one of the most important parts of a functional specification because no one thinks about what’s not there. It’s the best place to clear assumptions especially for the project commissioner. This sections sets the bounds of the project, without it stake holders will likely drift from the project requirements and start implementing undocumented features that push on the project deadlines and is sometimes unwanted.

Why Use Cases

Use cases are in my opinion the best way to explain how the end user will experience the application. They are in story form making them easy to write and understand. They provided a neat and clear way to document the features of a system while providing a framework that keeps the writer form creating a novel. They provide an easy way to write up technical specifications and system documentation. A use case can be copied and pasted to a technical document, the technical documenter simply writes a paragraph on how the system will accomplish the use case.

User Personalities

If the system has different user experiences and user roles it’s a good idea to create user personalities or personas(as they are called in UX). A persona is a good way of getting people to think in terms of the end user experience. They make excellent references in conversation when trying to express an idea. Personas keep developers focused on providing relevant security and user permissions in a multi tenant system. Designers use them for create great user experiences by imagining the persona using the system as a real user would. It’s advisable to create a separate section before the use cases start to introduce all the personas to the stake holders, this makes them referenceable in the use cases as well.

User Interaction Sections

It’s in my opinion a good idea to split the functional specification into feature areas. Ex. on an administration system for a blog, list the headers as: blog posts, blog post categories, blog post comments, user administration, etc. This makes it easy for a developer, end user, software architect or documenter to address only the part of the system that they care about at a particular point. Under each of these sections being listing the use cases. Pay attention to what is not there, if a persona does not have access to that area state the fact clearly do not ignore it.


Some parts of the document will only be addressed to a particular stake holder. The best way to do this, is by using coloured text areas and explaining their use at the introduction of the document.

Signing Page

If you require a signing page it should be kept separate form the rest of the document. It should have a clause stating that previous functional specifications will be voided by signing this document. This way every time a functional specification is updated as the project progress all the parties are protected by the agreement and the document becomes malleable.