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