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:Thu, 3 Jun 1999 00:37:31 -0600
Susan Harkus wrote:
> Who will use the information in your functional spec? Analyse
> the information needs of your users and prototype some
> information capture/presentation formats. When you and your
> users agree on what they need, review the prototype and see what
> you can leave out. Get agreement on the final format and start
> writing. This is really quite a short develop-refinement cycle
> if all stakeholders are available to provide feedback. One or
> two days?
>
> . . .
>
> Although people talk about document types, it all comes down to
> the fact that people have their own expectations about what a
> document should contain based on their information requirements.
> Even if your organisation says it needs a functional spec, what
> that item becomes will be a customised solution that meets the
> stakeholders' needs.
Just wanted to express my total agreement and add one more
thought. First, here's the agreement part. The first two
questions to answer when writing any technical document are Who's
going to read it? and What job are they going to do with the
information? Only then is it possible to select the information
and form in which to present it in a way that does something
useful for real people. Here on TECHWR-L, we usually talk about
user's manuals for software, but as you point out, in effect,
these same two questions also apply to the internal "scaffolding"
documents produced during development.
For some reason that I'm sure is of profound anthropological and
psychological importance, there's a deep, human temptation to
avoid asking these questions when writing scaffolding documents
like requirements and functional specs (or whatever people call
them). The temptation is to write to an abstract standard of
correctness, not to real people and a real situation.
The abstract standard usually derives from books, standards
organizations, a person's previous place of employment, or just
whatever the person first heard was "correct". The most common
manifestation of this temptation is to write a document by
filling in a prefabricated, "standard" table of contents, usually
called a "template". The problem that the document needs to
solve *here and now* never seems to be addressed, only the
abstract problem of conforming to some pre-existing standard that
may or may not be relevant on this one project.
I don't know all the reasons for that temptation, and I'd love to
hear some hypotheses. But I think that one of them is the fact
that software development for many years has been and remains in
a state of conceptual confusion. People don't yet know exactly
what problem programmers solve or how to characterize it.
There's not even consensus on where is the line between
specification and design. (This is the "one more thought".)
If you ask an electrical engineer to design a transformer for
you, you know exactly what to tell him: the input voltage, the
output voltage, the frequency, and the power consumption and heat
generation characteristics. More importantly, if you don't know
everything to say, you can just ask the engineer. He can tell
you exactly what information he needs in order to design the
transformer.
But if you ask programmers what information they need in a
requirements document (or functional spec, or whatever), they
very often aren't sure. Even the ones who are sure what they
want have very different conceptions of what that information
should be. The best you usually get is something terribly vague,
like the traditional "what the software should do, not how it
should do it." Not to pick on Tony Markatos, since that's the
distinction that's been taught widely for many years now, but
"what vs. how" doesn't much help the person writing the
document. Notice that the electrical engineer can do a lot
better than, "tell me what you want the transformer to do, not
how you want it do it." He can tell you specific parameters for
you to fill in. He can tell you what he needs at a much lower,
and more useful, level of abstraction.
With no clear answer to the question of what people do with these
scaffolding documents or what information needs to be in them,
it's only natural that people latch on to *some* more-precise
standard for that information, like a template. But here's the
trouble with that temptation: it takes different kinds of
information to specify different kinds of software. What's
relevant to the developers for one software product might be
almost completely irrelevant on another project.
Even the development roles are different for different kinds of
software product. Sometimes user-interface design is the
majority of the job, and sometimes there is no user interface at
all! (Compare a video game with a controller for the fuel
injectors in a car.)
An analogy is that the information needed to specify a
transformer is very different than the information needed to
specify a radio receiver. No sane person would consider
following a standard "electrical-device requirements template"
that had a single set of sections and subsections to be applied
indifferently to *all* electrical devices. Yet that is exactly
what people propose in software. There's one "correct" way to
write a func spec, regardless of the type of software, and anyone
who even thinks about doing it any other way is "wrong", etc.
So I can't offer a general answer to, "What information should be
in a functional specification?" and indeed no one can (without
being excessively vague). My book takes the approach of
describing a few different checklists of information needed for
specific problem types and inviting you to mix and match these
checklists according to the specifics of the project. I make no
claim to generality, though. For example, I have no idea how to
write the requirements for neural-net software. I figure the
information needed to specify an applied neural net is radically
different than anything I've ever been involved with, so I
couldn't even presume to say what it should be.
But I can suggest that in addition to the always-critical steps
of talking to the readers of the document to see what they want,
as well as trying out ideas and getting feedback (exactly what
Susan suggests), a lot of the considerations about the content
and organization of the document should be project-specific, not
boilerplate. In other words, don't expect to talk to the
programmers and testers once and then have a template that you
can reuse. You need to talk with them about these things and
make major adjustments to the document on *every project*--not
refining a template to an ever more perfect, universal standard,
but making each document fit the unique needs of each individual
project.
