Summary: functional specifications

[geoff-h -at- MTL -dot- FERIC -dot- CA]

 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.