Re: Software documentatio

Subject: Re: Software documentatio
From: Glen Accardo <glen -at- SOFTINT -dot- COM>
Date: Mon, 8 Aug 1994 14:27:02 -0500

> subject about which I feel very strongly. Of course writer's should be
> involved in the initial stages of product design. The fact is, however,
> that most writers don't really have a grasp on how they can be of help at
> that stage. Sure, if you're involved in early design your job of
> documenting will be made a great deal easer (and arguably, this has benefits
> to the organization as a whole) but if the writer doesn't show how he/she
> can produce quantifiable benefits, he/she has no right to expect to be

Well, I am currently coming into a project at the absolute last minute. My
cohort and I have to generate ~600 pages of documentation (online and paper)
and we have about six weeks to do it. Now, 10 pages per day isn't that bad,
since we have some base material which we can use, but the worst part about
coming in this late is that WE DON'T KNOW ANYTHING ABOUT WHAT WE'RE
DOCUMENTING! Five pages per day is a better estimate of what we can really
do because we'll have to learn the product as well.

The design document we have is essentially useless. About 80% of it is stuff
that "all windows programs do" and offers no insight into what the program
really DOES. Had I been involved from the beginning, I could have suggested
a few things to make my life easier, and keep the developers from wasting
their time describing, in detail, things we already know.

Early involvement by tech writers can be passive. Sitting and listening can
help us learn the product early, make better estimates of what we have to
document, and get us further along the path to "total understanding" of the
product. Translation: better planning and better manuals. When you add to
the mix the fact that many tech writers are computer nerds who choose to
write sentences instead, that we can help identify nasty spots in the
interface, and do a few other things -- we should definitely be in on design!

Now if you'll excuse me, I have to go tell my boss that his deadlines are

glen accardo glen -at- softint -dot- com
Software Interfaces, Inc. (713) 492-0707 x122
Houston, TX 77084

Did the Corinthians ever write back?

Previous by Author: Re: YABM*!
Next by Author: Information for UNIX Help stuff (fwd)
Previous by Thread: Re: Software documentatio
Next by Thread: Re: Software documentatio

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

Sponsored Ads