Login

Writing A Functional Specification

Writers hate coding, and developers hate writing. And never the
twain shall meet…except, perhaps, in a functional specification. More,
inside.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!{mospagebreak title=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.{mospagebreak title=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.{mospagebreak title=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.{mospagebreak title=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.{mospagebreak title=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.{mospagebreak title=The Color 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.{mospagebreak title=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.{mospagebreak title=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!