Re: Software documentatio

Subject: Re: Software documentatio
From: Brian Bennett <bb18+ -at- ANDREW -dot- CMU -dot- EDU>
Date: Mon, 8 Aug 1994 16:19:42 -0400

At 02:27 PM 8/8/94, Glen Accardo wrote:

>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!

I'm not saying that you shouldn't "definitely be in on the design." I'm
saying that unless you are part of a mature development team (one that
realizes that what benefits you benefits the whole product, or team) they
are simply not going to care about your needs. I would bet that the spec
you are using is not useless only to you, but also to the other groups who
use it (including the authors themselves). It would probably be easier to
convince the team that allowing you to manage and control the spec would
benefit the entire team than it would to convince them that "passive"
involvement will benefit the entire team. In fact, if the overall
organization is fairly immature, they'll probably fail to realize how this
involvement would benefit you.

If you can't convince 'em, show 'em.


Brian S. R. Bennett
Senior Information Developer
H. B. Maynard and Company
Eight Parkway Center
Pittsburgh, PA 15220

Phone: 412/921-2400 ext. 123
FAX: 412/921-4575

Previous by Author: Re: Software documentatio
Next by Author: Writing guidelines
Previous by Thread: Re: Software documentatio
Next by Thread: Re: Software documentatio

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

Sponsored Ads