Establishing a documentation process

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.


Previous by Author: Re. Keeping up with modern English
Next by Author: Re. HTML vs. Acrobat
Previous by Thread: Re: File and graphics managing software
Next by Thread: Re: Establishing a documentation process


What this post helpful? Share it with friends and colleagues:


Sponsored Ads