TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:Re: Definition of a functional spec From:Ben Kovitz <apteryx -at- CHISP -dot- NET> Date:Wed, 2 Jun 1999 12:43:22 -0600
Michelle Tuohy wrote:
>anyone know a good source of a breakdown of the content of a functional
>spec? depending on who i talk to here (marketing, development, quality
>assurance), i get a different (but similarly vague) idea of what should be
>included.
>
>btw, the subject of the spec is a decision-support application that consists
>of a front-end (a la vb but not quite) to a complex knowledge base.
Here's an old message I posted to TECHWR-L that breaks down
different kinds of documents sometimes needed during software
development:
That message doesn't call any of the documents a functional
specification, only because the term "functional specification"
gets used pretty broadly. And vaguely. It vaguely refers to any
of the first three documents listed: the requirements document, a
user-interface design doc, and/or a machine-interface design doc
or API.
All of the documents listed there are intended to be detailed.
If you're still in the early stages of planning out the project,
you might want to just start with some kind of "product vision"
document that's no more than a page or three. That's not enough
to hand off to programmers, of course, but it can provide a good
starting point for conversations about the precise requirements
and user-interface design.
About how to attack the requirements for a decision-support
system, the following is only a guess, since naturally I'd have
to know more about the project, but this might at least be a good
start at listing the information that you need to start designing
the user interface:
1. What is the subject matter of the decisions and the knowledge
base? Defining the subject matter amounts to defining a bunch of
sets and relations between them: doohickeys have such-and-such
parameters, widgets have so-and-so parameters, every doohickey
connects to two or more widgets, etc.
2. What information would you like users to be able to view? In
what form would you like them to be able to view it? Partly this
would include a list of questions to ask about the above-defined
subject matter, but most likely it would also include
calculations that you want the system to make or rules that you
want the system to apply to the data.
For example, in a decision-support system for planning
construction work in a telephone network, you might want the
system to calculate the costs of maintaining some hypothetical
new network facilities (a calculation), and to show a map of a
geographical area with areas likely to be underserviced in the
next year highlighted in red (a rule and a form in which users
view information). You'd have to define exactly what constitutes
"underserviced" and how the system is supposed to predict network
usage in one year's time from current data in the knowledge base.
This might entail providing formulas for making calculations
based on rates of population growth and construction.
The hard part, by the way, is #1: defining all the concepts that
go into #2, precisely enough for people to address by
programming. If your knowledge base is already constructed,
though, it probably has the subject matter already defined, so
you can just reuse that and get straight into #2 (the fun part).
Here are a couple mistakes to avoid:
- Filling in template with a prefabricated table of contents
and calling that the functional spec. Your system may well be
one-of-a-kind. While there are some common pieces of
information that belong in a software requirements document,
like what platform you want it to run on, the majority of the
information should be project-specific, and organized in a way
appropriate to this one project.
- Writing only "high-level" requirements and deferring the
details to the programmers. The programmers probably don't
know much about the subject matter of the decision-support
system or what would be good ways of supporting decisions.
Giving them this information is why you write a requirements
document. For a little more on why a requirements document
needs to be detailed, you might take a look at this page:
