Summary: functional specifications

Subject: Summary: functional specifications
From: geoff-h -at- MTL -dot- FERIC -dot- CA
Date: Fri, 30 Jan 1998 08:00:32 -0600

Some time back, I asked for some details on producing a
"functional specifications document" for a colleague
who's just starting to design some new software. I've
summarized the responses I received plus added a few
points of my own:

Functional specification documents detail the functions
(e.g., procedures, capabilities) of a system. The document
contains a section for each function or group of functions,
and each section typically contains a definition of the
function and explanation of its purpose (plus those of any
optional functions), a process flow chart, an explanation
of the chart, flow rules, process rules, business rules,
minimum data requirements, scripting requirements,
reporting requirements and interface details.

The document should begin with an overview that provides
any necessary background or context (e.g., like an
Executive Summary), information on what the spec covers
(and doesn't cover), time frames (if you're in a project
management environment), generic rules for the
programming, and an indication of the objectives and scope
of the project. Include appendices on any issues that need
to be resolved (but couldn't be resolved during the
initial and subsequent design meetings), and lists of your
assumptions, design standards, system constraints, risks,
and implementation considerations. You can also include
summaries of any reports required, screens, etc. A few
more details:

- A series of screen captures or thumbnail sketches is
insufficient.
- Include information on the underlying data structures and
how the parts inter-relate (i.e., the behind- the-scenes
processing that occurs). Similarly, describe the software's
"logic" well enough that everyone will know the approach it
takes to solving various problems. (IMHO, understanding
this is the first and crucial step in understanding how a
user will or must use your software and thus how they will
enter your documentation.)
- Document all relevant file names (user files as well as
programmer files).
- Use a description of what the user can do with the
program as the basis for your user interface, and design
to meet the interface rather than patching the interface
to match the code.
- Identify any menu items that have been created, added, or
changed since previous software versions.
- Define the software's modes of action (e.g., edit vs.
display mode, how buttons and other widgets change when
users add data or change a setting, whether data are
saved or updated upon entry or after clicking a "save"
button).
- Define the parameters of any data that users can enter
(minimum and maximum, legal and illegal, meaning of various
settings, etc.), and distinguish this clearly from data
created, calculated, retrieved, or displayed by the
software itself.
- Minimize the amount of written text; rigourous and
concise functional specs can be based largely on data flow
diagrams and entity relationship diagrams.

One respondent also suggested doing a web search for
"2167-A" and the related "functional requirements
specification (FRS)". Another suggested two references that
deal with the subject briefly: Principles of Communication
for Science and Technology (L.A. Olsen and T.N. Huckin) and
Writing and Analyzing Effective Computer System
Documentation (A. Stuart).

Michael Collier has put together a web site for software
development documentation, with a link to a page on
functional specifications. In exchange for providing this
resource, he'd appreciate hearing your comments on the
usefulness of the information and its presentation:
www.geocities.com/SiliconValley/Lakes/4970/
Steve Whalley (stevewhalley -at- man -dot- brite -dot- co -dot- uk) has also
offered "a fairly detailed outline structure (a document
plan really)" by private e-mail if you're interested;
contact Steve directly, but be nice to him: if a thousand
techwhirlers all accept his offer, he's going to be busy!

Anthony Markatos made a crucial distinction that serves as
a nice conclusion for this summary: functional specs
specify WHAT the system is to do, whereas design specs
should be used to describe the HOW. Failing to make this
distinction undermines your efforts and produces an
ineffective document.

Thanks to Michael Collier, Kim Cramer, Suzy Davis, Niki
Dow, Chris Hamilton, Mike Ingram, Anthony Markatos and
Steve Whalley for providing inputs. (Thanks also to anyone
who provided comments directly on techwr-l; as I noted in
my original message, I'm too far behind on digests to have
had a chance to see your messages yet.)

--Geoff Hart @8^{)} geoff-h -at- mtl -dot- feric -dot- ca
Disclaimer: Speaking for myself, not FERIC.




Previous by Author: Learning to type
Next by Author: Correction: Functional design specs
Previous by Thread: Re: Summary: functional specifications
Next by Thread: STC Metro Baltimore chapter meeting


What this post helpful? Share it with friends and colleagues:


Sponsored Ads