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: Teaching programmers to write From:"Susan W. Gallagher" <sgallagher -at- EXPERSOFT -dot- COM> Date:Wed, 21 Jul 1999 10:31:09 -0700
>...company searching a technical writer has no writers yet. All the
>documentation is written by the programmers. They want to hire a tech writer
>to teach the programmers how to write manuals for their inhouse users (the
>company is a bank).
Rather than teaching the programmers to be writers -- a daunting task
if ever there was one ;-) -- just help them to write the documents they
need to write.
The bad habits you need to work on include:
* The tendency to tell *how* a program works and *why* it works that
way without ever touching on *how* it should be used.
* The tendency to think that writing is very different from speaking
and to write effectively they have to alter their language significantly
to make it sound more formal.
There should be some level of consistency in the kinds of programs they
are creating. Use your skills to group their output into program types
and develop skeletal outlines they can use. This will help them to
control the structure of the doc; give them a "fill in the blanks" form,
if you will. If the outline is well constructed and detailed enough, it
will guide them into the *how* of using the application and eliminate
the wasted time of documenting how the program was created. Your teaching
task then becomes teaching them how to use the outlines.
Develop a style sheet and include standard verbiage. For example, specify
whether buttons should be clicked or clicked on and whether they should
be known by their name alone (as in "Click Help") or whether the word
"button" should be included (as in "Click the Help button"). Your teaching
task then becomes teaching them how to use the style sheet, how to find
the info they need, and when to use the standard verbiage.
Remember that documenting software is not their job, developing it is.
They will, in all liklihood, be resistant to both the task and the
training. The easier you make it to use the tools you create for them
and the more enjoyable you make the training classes (think edu-tainment
here), the more effective you'll be.
