Value added by technical documentati

Subject: Value added by technical documentati
From: "Virginia J. Link" <LINKVI -at- MAIL -dot- STATE -dot- WI -dot- US>
Date: Fri, 7 Mar 1997 15:43:59 -0600

So this discussion leads me to my burning issue: where do technical writers
belong in the development/testing/production phase? If we have to
document/bandage bad UI and programming (and take the heat for manuals that
are too big, too costly, too late, blah blah ad nauseum), don't we really
belong in the picture long before the code is codified?

Early on in the development process of a massive project, I tried to derail
some really bad, hand-me-down screen design, screen titles and techno
jargon, but was defeated/deleted, ignored, and otherwise treated like an
irritating mosquito. They insisted on using the same titles on the
"transfer" system that the originating state had used. For example, we
couldn't possible change "Inquire" to "Query" or "View." No, we have to
have screens titled "Inquire Participant," and documentation which reads
" add, update and inquire participant information." And then there's
the ever-lovely "Participant Employment Supplemental Maintenance" screen.

We also have instructions to "path" to this screen or that before "pathing"
to some other screen.

We have a function called "Document Generation Facility," which, of couse
leads to DOCGEN.


Where the online screen-level help should be, there's a screen that pops up
and basically says, "You obviously pressed the Help key hoping desperately
that there'd actually be help here but ... THE JOKE'S ON YOU!"

My edits on the user manual materials conveniently arrived back in my lap
after the job of fixing the manual landed on my to-do list.

We paid millions of dollars to contractors and subcontractors for this
system and its documentation.

Whew! (Head swiveling around back into place) Sorry about that! It might
be apparent that this has been bugging me for a few years now. Anybody else
been in this situation? Been there, done that? Do I have to go back to
school and learn programming to short-circuit these "too much, too little,
too late" blues?

aka V. Link
<Somebody snipped...
Paul Branchaud[SMTP:paul -at- VEDGE -dot- COM] wrote:

The best sign that you have provided customers with good documentation
(IMHO) is if the technical support lines are quiet. Although I have no
proof, I feel there is a direct correlation between the quality of
documentation and the
number of calls a technical support line gets with regards to a specific
I have heard it said that the goal of good documentation is to eliminate the
need for technical support. The goal of good user interface design is to
eliminate the need for documentation.
<end snips>

TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot- Send commands
Search the archives at or search and
browse the archives at

Previous by Author: Dr. Seuss
Next by Author: Re: E-mail, Email
Previous by Thread: Re: ForeHelp for Win3.1 and HTMLhelp [Ref:C426116]
Next by Thread: Re: Value added by technical documentati

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

Sponsored Ads

Sponsored Ads