Writing A Functional Specification

The Big Picture

Every software application can conceptually be broken up into three layers: the front end, which consists of the user interface and application controls; the middle tier, which consists of the code; and the back end, which consists of the database, data structures and other assorted gremlins.

When building software, the trick is to design in such a way that when you place these layers one on top of the other, the parts fit exactly. This is far more complicated than it sounds, and fairly difficult to do at the best of times. But don’t let that discourage you - a number of tools are available to assist in this process…and one of the better ones is called a functional specification.

A functional specification can substantially simplify and streamline the process of application development. Intended to describe how a piece of software works, it provides a ready reference for software developers and aligns large and disparate development teams to a single goal. In the process, it provides technical clarity on how the different components of a particular applications are to be designed, implemented and integrated with each other, and (if used correctly) significantly reduces the time and cost component of any development exercise.

Intrigued? Wanna meet one of these creatures? Flip the page, and let’s get started!

Getting Formal

According to http://www.whatis.com/, a functional specification is “…a formal document used to describe in detail for software developers a product’s intended capabilities, appearance, and interactions with users…”. Webopedia at http://www.webopedia.com/ has a similar definition - it calls a functional specification “…a formal description of a software system that is used as a blueprint for implementing the program…”.

A functional specification is written primarily for the development team, with the objective of providing the members of that team with all the information they need to begin designing an application. It aims at outlining the entire experience of the application, without really getting into the details of implementation, thereby providing the developers with a comprehensive knowledge base and reference for any and all questions concerning the project. The idea here is for the kinks in the design to be worked out at a conceptual level, and (more importantly) for the customer to get a clear idea of what the deliverable is and how it will work.

Once finalized and approved by the customer, the functional specification can be used by a software developer to create a detailed software design document, which contains high-level architectural diagrams of the system, together with descriptions of the components used and their relationships via a modeling language. Application development then becomes a matter of implementing what has been frozen in the specification.

The level of detail in this document varies from project to project and company to company, and depends on the level of complexity inherent in the project, and the amount of time and staff available to compile the data obtained into a structured report. If you’re an independent developer or a project manager with a small team, you might prefer a smaller, simpler document; if, on the other hand, you have a full-fledged team behind you, work in a large, process-driven organization and/or have a complex project to tackle, you might prefer a document that drills down to the very last level of detail.

Of Time And Talent

The functional specification should be written by a person who is isolated from the actual development of the software, so as to add a degree of impartiality and independent thinking to the process. Obviously, this person needs to have a wide range of skills: an understanding of how users think; a thorough knowledge of the capabilities of various programming languages and tools; the experience and creativity to break down a large and complex project into smaller, discrete modules and data structures; and, most importantly, the ability to communicate all of the above in a clear and concise fashion via a formal document.

This, you will agree, encompasses a fairly wide (and hard-to-find) range of talents, which may require years of experience to develop. But talent is just one of the things a functional spec writer needs…time is the other.

Contrary to what you might think, creating a functional specification is a fairly time-consuming job. As a functional spec writer, you need to spend a fair amount of time understanding the requirements and business vision for an application, discussing design and implementation with the development team, and mapping the two together to ensure that the final deliverable satisfies the customer’s needs…all before you can even begin to think about structuring this information into a formal document. This process is, obviously, not something that can be accomplished in a matter of hours; depending on the complexity of the application, creating a detailed functional specification can consume days or even weeks.

In case you’re wondering whether the process is really worth the time, the answer is a resounding yes. The consequent benefits of the process - a streamlined development process, better risk and change management, greater clarity in the development team and fewer course corrections - all add up to a substantial cost and time benefit in the final analysis.

Laying The Foundations

With the advertising out of the way, let’s take a look at the typical components of a functional specification.

As stated earlier, the functional specification begins where the requirements documents ends, and it performs the important function of describing how the deliverable will meet the items listed in the requirements spec. It must therefore begin with the identification of the purpose of the application and the business objectives to be fulfilled by it.

These objectives serve as the basis for derivation of the features required in the application. It’s important to spend time on making an exhaustive list of all the features that are required, although there will always be a few errant ones that you will miss out on in your first attempt.

Next, the target audience for the application should be described. Direct interviews and user profiles are just two of the methods that may be used to arrive at an idea of the audience base. Important factors to be captured here include age, educational background, most common uses for the application, current workflow for those tasks, and comfort level with similar applications. It is also important, at this point, to get an idea of the different user roles that the application must support, to assist in designing security and privilege systems that will be implemented later.

With all this information at hand, you can make the first stab at structuring all the raw data into a more organized framework. A good approach to follow here is to use the data collected about the features required and the workflow followed by the target users to divide the application into modules, which in turn encompass the relevant features.

I, User

At this point, you, in the role of the spec writer, actually enter the realm of deciding the user experience. And, needless to say, you will need all your wits about you to successfully complete this process - a mistake here could have significant repercussions on the user’s perceptions of the application’s ease of use.

In this critical phase, models can play an important role in designing, developing and testing assumptions and ideas about how the application should be structured. Essentially, a model is a structure diagram that helps the writer depict application components and the features included in each. Models may be defined from the point of view of both the user and the developer: a user-based model is the user’s conceptual view of the application and is guided by user research and studies, while a developer-based model focuses more on the architecture and data structure - modules, programming interfaces, logical relationships et al - of the application.

You can also consider representing information using diagrams and flowcharts - for example, data flow diagrams, which indicate how data is stored and processed by the application, and object interaction diagrams, which provide an overview of the objects that make up the application and their interaction. In case your application uses a database, you might also consider including one or more entity relationship diagrams to represent the design of your database.

An important thing to note here is that, in the garb of the user experience, you are more or less structuring the application. It is therefore essential for you to talk to the development team in detail about the constraints and assumptions that they will be working with. A detailed analysis of this kind saves the entire team a lot of wasted time and frustration in later stages.

The Screening Process

Once the components of the application are decided, the next step is to detail the application workflow. In this stage, you would examine each and every feature that has been decided upon, and come up with screen flow diagrams or schematics that clearly delineate the important elements of the interface, and the relationships between them.

Among the items that should be meditated upon here are:

• The screens required for each function

• The placement of screen elements

• Navigation between screens, and the various points of access of the screens

• The data captured from the user at each screen, including data types, validation rules and constraints; source and destination containers for the data; and the data processing logic and business rules applicable at each stage

The depiction of each of these functions can be aided with a prototype, if the budget can support it; this prototype comes in handy to verify that your assumptions and design decisions work in a real-world environment, and to get real feedback from project managers and client representatives that things are proceeding in the right direction. When asking for feedback, it is important to always restrict the discussion to the core issues at hand, in order to avoid the discussion digressing into issues of fonts and branding rather than navigation and screen layout.

Another good idea, and one that I use often, is to include a top-level flow chart showing the relationships between functions, modules and screens; the data elements controlled by each; and the interfaces between each. This provides readers and reviewers with a big-picture overview of how the application is structured and gives them a reference point to go back to in case they get lost, in much the same way as a site map on a Web site does.

The Colour Purple

With the workflow decided, the next step is to define the look and feel for the application’s user interface. At this point, you will finally have to commit to things like the interface metaphor, screen colors, branding and related items. Much of this information will come from detailed discussions with the organization’s interface design team, and will be based heavily on the prototypes created in the previous stage.

Care should be taken at this point to ensure that the filling in of the skeletal structure decided in the previous phase does not have the unwanted effect of making previously-simple items complicated - for example, by adding visual enhancements that distract (rather than enhance) the user experience. The typical example here is that of the flashing banner advertisement - it’s a definite attention-getter, but it usually ends up annoying more users than gaining customers. And if you’re building a new product, anything that increases your user’s already-high stress level is a definite no-no.

It is for this reason that you, in the role of specification writer and moderator, must interact closely with the interface design team and provide feedback if the interface begins complicating, rather than simplifying, common functions. As in all other aspects of life, the KISS principle has a role to play here too.

It’s important to take into account the client’s branding requirements at this stage also. Selection of the screen colours, a clearly-visible logo or brand image, the attitude and spirit conveyed by the various elements of the interface must all be in sync with the client’s needs and desired image. To this end, care should be taken to involve the client’s marketing or brand equity personnel in discussions of the user interface, so as to avoid design changes at a later date.

Hitting The High Notes

At this point, you have all the information needed to begin writing the functional specification. Here’s a list of the high notes - make sure you hit them all!

• A very, very important rule of creating specifications is to be consistent and extremely precise in your use of words. For example, if you’re using the word “function” to indicate the, well, functions of your software, you shouldn’t at any point switch to “features”, “commands”, “menu items” or “actions”. To this end, make yourself a glossary of the terms that you’re going to use right at the start, and stick to them consistently. Add this glossary to the end of your specification so that your readers have a ready reference, and to ensure that developers can communicate with each other using the right words.

• Conventions in the document lead to patterns that the users can grasp. They then start expecting information in a particular format, thus increasing their level of comfort with the document. Using consistent styles also speeds up assimilation of the information, and helps spot particular information easily on re-reads.

• Headings are a powerful tool in making a huge mass of text look manageable. A common model is that as you go deeper in a particular topic, you indicate that by descending prominence of headings. So, all top level headings will be, say, in a large font size and bold typeface, with the next level taking a smaller font size, and so on. You might also want to number the headings to help users understand the grouping of information.

• Use bullets and numbering to break up complex concepts into simpler, smaller information nuggets. The convention here is to use numbering for sequential information only and bullets for information that is best presented in points instead of a paragraph. Bullets also allow you to group together points related to a concept and ascribe them levels of importance.

• Use screen grabs, schematics or flow diagrams to increase the efficacy of your document. Since a functional specification also includes information on what the user will see in the application, it will include schematics, screen flow diagrams and sample screens. These screen grabs will be used by the developers to ensure that the final product conforms to what has been decided in the specification. Ensure that you are consistent in your usage and labeling of screenshots.

• Ensure that nothing is left open to interpretation. Since this document will be used as a guideline for the actual implementation of the application, it’s important that it be clear, concise and accurate at all times. Ambiguity and a failure to resolve troublesome points are sure signs of trouble in the future.

Sealed With A Kiss

Last, but definitely not least, is the review of the functional specification. As I mentioned above, this is a document that is approved by the customer as a token of acceptance of the application you offer him, and therefore needs to be completely free of loopholes and ambiguity.

The first level of review will be performed by you, the writer. The usual checks that any written document goes through - proof-reading, editing, formatting, spell-check and grammar-check - definitely apply. Beyond this, you might want to test the document on a designer or developer, to see if it makes sense to them.

Next, the project mangers should review the document to see if it is implementation-worthy. Since these are the people who will be using the functional specification in the next level, you can expect them to get back to you if they find that any of your design decisions violate the constraints under which they will be working.

Incorporation of changes suggested during the review stage needs to be done very carefully. Be sure to incorporate changes at all points in the design that are affected by them. Noticing an incompatibility after customer sign-off is extremely time- and cost-consuming.

Once you have a functional specification that has been amply thumbed through by the internal team, you will be ready to show it off to the customer. Remember to discuss, in detail, any changes or additions that the customer asks for, and incorporate the changes for re-review only when you are completely clear on their impact.

Once you’re all done and your team has started using the document to build a more technical design specifications, you can relax - your job is done, and you’re all ready to take on the next challenge. Happy writing!

Note: Examples are illustrative only, and are not meant for a production environment. Melonfire provides no warranties or support for the source code described in this article. YMMV!