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: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
"...to 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.
We have ALL CAPS ON EVERY SCREEN.
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?
Rumpelstiltskin
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
product.
==========
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
to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
Search the archives at http://www.documentation.com/ or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html
