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.
> > How many of you have been asked to document a software application,
> > but were not expected to need access to that software?
>
> It seems quite impossible to document software you can't see.
Hmm... A software specification is documentation, and it's written
before the software even exists.
It's true that all software specs are abysmally bad... But that's just
because they're written by engineers, not necessarily because they're
written in the absence of a working product.
It's also true that specs are usually out-of-date and don't match the
product, and most of them are incomplete and have inconsistent,
inappropriate levels of detail. That makes life difficult for the
techwriter who has to turn the spec into a user's manual, but it's a
disaster for many others as well. Without an accurate, complete spec:
developers don't know what to work on,
their managers can't accurately schedule anyone's time,
testers don't know what to test,
Marketing can't prepare promotional literature,
Tech Support can't prepare training materials,
etc.
And... Without an accurate spec, no one knows when the product is
finished! Very few development projects begin with a spec that only
says, "We'll just start working, and we'll keep working until some
arbitrary date in the future, and then we'll ship whatever the hell
we've created, with a haphazard manual written at the very last minute,"
but LOTS of them end that way.
So how can all that be avoided? Think about the ideal: The software
conforms exactly to a well-written, easy-to-understand spec, and that
spec is written with exactly the right amount of detail (I'm talking
about functional specs here, so that means a complete and accurate
description of WHAT the thing does without saying HOW it does it --
i.e., no unnecessary implementation details). Because the spec matches
the software, a user's manual can be written by referring only to the
spec... And because the spec is well-written, writing the user's manual
requires practically no effort.
I'm not a pro technical writer -- I've written fewer than a dozen Frame
documents, and only one of them was over a hundred pages -- but I worked
for a long time as a freelance consulting engineer, and I found a
foolproof way to get my clients to write good functional specs that
nearly matched the ideal I just described:
Write the User's Manual FIRST.
The thing is, you have to write the damn thing anyway. Writing it first
-- making IT your functional spec -- solves all the problems that
development teams and technical writers traditionally have with formal
specs:
1. Because it's a user's manual, it includes all the important
functional description while neatly avoiding the common problem of
specifying too much implementation detail. Because it necessarily must
include the ENTIRE functional description, it forces the spec authors to
really think about what they're defining: The user's-manual format
makes it very difficult to gloss over areas where they haven't thought
things through.
2. Because it's a user's manual, it's easier to read than a big formal
"engineering spec", which means that it's much easier for its authors
and reviewers to spot awkwardness in the interface, internal
inconsistencies, missing or unneeded features, etc. A formal spec can
be reviewed by engineers, but a user's manual can be reviewed by ANYBODY
-- even the product's intended customers, no matter how non-technical
they might be -- so the spec can incorporate their suggestions before a
single line of code has been written.
3. Because it necessarily specifies every funcion completely, it makes
scheduling easier. Wait, that's wrong... What I mean is, it makes
REALITY-BASED scheduling POSSIBLE. Scheduling is still hard, but
without a functional spec written to the high quality level that'll be
achieved by writing the user's manual first, schedules can only be based
on wishful thinking and hand-waving, and will never be believed by
anyone but your company's dumbest salesperson.
4. Because it's a user's manual and those are written by technical
writers rather than engineers, you'll be involved at the earliest stages
of the product's development... So YOUR valuable input gets considered
in the design.
5. At every moment in the product's development, its user's manual has
already been written and reviewed, so when the product finally IS ready,
it can ship immediately with full documentation. If an emergency occurs
and you must ship an early, unfinished version of the product, it's
really easy to snip from the complete manual the descriptions of
unimplemented features, so even that early version can ship with very
good documentation.
For any reasonably complex product, someone will of course have to write
an implementation spec... But that one SHOULD be written by the
engineers who'll be developing from the functional spec/user's manual,
so it can be whatever format they like. Ideally, they'll write the
implementation spec before they start working on the software, but even
if they just sorta make it up as they go along, having a user's manual
from the start ensures that they'll always have a clear, definitive
guide to keep them from going off-track.
Sorry this was so long... Hadn't planned for it to be.
-Andrew
=== Andrew Warren - awarren -at- synaptics -dot- com
=== Synaptics, Inc - Santa Clara, CA
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
WebWorks ePublisher Pro for Word features support for every major Help
format plus PDF, HTML and more. Flexible, precise, and efficient content
delivery. Try it today! http://www.webworks.com/techwr-l
