TechWhirl Sponsors

About TechWhirl

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.

It's not a matter of determining the structure of the document
and writing it? I'll talk with the prospect tomorrow, but his
inquiry leads me to believe there are no people there now who
know about these types of documents.

If it's up to me to find a document structure or template, do you
have any specific suggestions?

Specific suggestion? Check the archives for references to IEEE and ACM,
both of which have well established standards that a lot of
organizations use. I don't think either offers their templates for free,
but I could be wrong about that. In any case, the same archive check may
turn up other possibilities.

That said, you have clearly understood the basic difference

between

functional and design specifications;

I'm not so sure that I do; there seems to be an awful lot of
overlap. And are "technical" and "design" specs the same?

You sounded clear in your understanding before. A functional spec is
written, as you say, from the perspective of the user. Input --> Black
Box --> Output. A design spec (sometimes separate from a technical spec,
sometimes part of it) describes at a minimum what the user interface
looks like; all the controls on all the screens or pages; all the
language used for field labels, on-screen instructions, error messages;
every possible consequence of every possible user action; all the
calculations (the equations or algorithms to be used). The technical
specification (if it is separate from the design specification) will
include the database schema; the messaging protocols; a clear
description of the architecture and the technologies involved; a
breakdown of what goes where (what functions go in which layer, what
goes into a .dll--or perhaps just into a header file or an include
file--so it's available to all the modules); what coding conventions
will be used (often specified in a separate document); what will be
exposed in the API; maybe some other stuff I'm not thinking of.

I don't want to "struggle
through" them; I want to write them. If has existing documents,
so much the better, but as I said, my initial impression is that
there are no documents that I would be able to use as a guide.

But struggle you will, at least until you get the rhythm of the thing.

Writing a functional spec requires a deep understanding of the problem
the software is going to solve and the environment in which the solution
is going to be implemented. You have to be the customer, in other words,
and think of every contingency, every usability issue, every interface
to not only the human operator but also other systems, the office or
factory environment, the Americans with Disabilities Act, the EU market
regulations, ..., everything. How does the product _function_ in the world?

Once you understand the reality of the product's being in the world, the
rest of the work consists of organizing the material sensibly (usually
with deeply nested decimalized headings), breaking it down into teensy
chunks (one requirement per heading, often a single sentence), and
writing clearly and unambiguously (your major contribution when you're
in a room full of engineers).

And the functional spec is the easy one ;-)

If the structure and design of every specification document is
different from company to company, then I have a great deal of
experience. But perhaps you are meaning something else. If so,
what do you mean?

I didn't mean it's all that different from company to company. I just
meant it's very different from other types of writing you may have done
and requires a somewhat different mindset. Content is king, and that's
what you have to wrap your head around--the thing rather than the words
used to describe the thing--in order to stand a chance of producing a
usable spec.

Learning about the software is all that would be required to
write a specification, but again, I fear I may be
misunderstanding you.

Well, the specifications are supposed to exist before the software
exists. The developers are supposed to find out about the software from
you, not the other way around. The old joke goes, "It's a tight
deadline, Marty. You go start writing code while I find out what the
customer wants." It's a joke because a lot of specs get written after
the fact, to satisfy a contract requirement. But that's not the way its
s'pozed t' happen.

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

SEE THE ALL NEW ROBOHELP X5 IN ACTION: RoboHelp X5 is a giant leap forward
in Help authoring technology, featuring Word 2003 support, Content
Management, Multi-Author support, PDF and XML support and much more! http://www.macromedia.com/go/techwrldemo

From a single set of Word documents, create online Help and printed

documentation with ComponentOne Doc-To-Help 7 Professional, a new yearly
subscription service offering free updates and upgrades, support, and more.http://www.doctohelp.com