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:Establishing a documentation process From:geoff-h -at- MTL -dot- FERIC -dot- CA Date:Thu, 7 Mar 1996 13:24:42 -0600
After months of nagging, I've finally convinced Management
to create a structure for producing documentation for our
software... not to mention for the software development
itself! (Our previous effort shipped without documentation,
and the user survey turned up a surprising <FeFeFe>
consensus: "We'd love to use the software, but can't figure
out how. Have you considered providing a manual?")
Now it's time to put up (since I didn't shut up). I know
the basic theory of integrating software and documentation
development, but I want to get the process nearly right the
first time... a large project is rolling downhill at me
with ever-increasing speed, and I want to impose some
structure on the process in self-defence.
Here's the simplistic outline that I'd like you folks to
help me fill in, modify or otherwise debug (I'll try to
participate in each stage, right from the start):
1. Define product features
2. Create mockup of user interface
3. Begin documentation of features and interface
4. Freeze features/interface (if not already done)
5. Complete documentation
6. Begin beta testing
7. Revision and final distribution
Notes: The documentation itself will follow our existing
review procedures, which work well, and we'll assemble a
style guide of some sort before we begin writing. Audience
analysis is already complete: we have a limited, captive
audience (the folks who fund our research), and both the
programmers and managers know their needs and
characteristics inside out. On the other hand, there isn't
a hope in hell of getting formal usability testing added to
the program on this first go around; I'm hoping to slip it
in unnoticed as part of the beta testing.
Please respond with a copy of your comments directly to me
so I can compile the results, summarize them, and forward
them back to the list. (I'm on digest, and it's nasty
trying to extract text... so please send me a personal copy
if you post to the list. Thanks.)
--Geoff Hart @8^{)}
geoff-h -at- mtl -dot- feric -dot- ca
Disclaimer: If I didn't commit it in print in one of our
reports, it don't represent FERIC's opinion.