RE: A sobering encounter (So now what?)

["Van Laan, Krista" <KVanlaan -at- verisign -dot- com>]

Keith Cronin wrote:

> I'll endanger myself by saying this, but part of why companies feel that
> secretaries and engineers can write the manuals is that the manuals
> produced by some "real" tech writers really aren't any better.

and some more good stuff. I also agree with what Andrew says about
content but I want to elaborate on both these messages a little to
throw in my two cents' on the tech-writers-adding-value topic. 
I meet a lot of tech writers who pay lip service to correct content,
but believe that the way to get correct content is to have a developer
write it for them so they can edit it and rearrange it, or to have
a developer tell them every single thing that needs to go into the
doc -- then they transcribe and depend upon the developer to read
and re-read to catch all the mistakes and add more information. This
is not only junior writers who do this, but people who have been in
the field for years.

In my experience, a tech writer adds real value when he/she saves
the engineers' and product owners' time. If a developer has
to write a lot of text, then read a series of drafts several
times to make sure no meaning was changed, the tech writer has cost
the developer a lot of time and distraction, maybe not producing anything
any better than the developer thinks he or she could have written
in the first place. I have a lot of experiences when writers 
won't write release notes, for instance. They want the 
product owner or an engineer to give them everything they 
need and then they'll just format it. My feeling is that if they read
the requirements, the change requests, and the functional specs, they
should be able to write 90% or more of the entire release notes. Then 
the developers and product managers will be simply reading a solid draft,
not writing it themselves.

If a writer really understands a product, the 
writer can make him or herself indispensable by tying together all
the pieces of content: how the product works, how it works for a
particular business application, how it benefits the user, and most
importantly, what information needs to go into a document. Even if
a writer has never used a particular application before, an experienced
one who has a good knowledge of the company's other products or
of similar products can put together a very developed draft 
with placeholders for the things they don't know. Then 
instead of sending out a general request for help -- "Tell me 
everything I need to know about this" -- their 
questions are very specific and always have a context. They figure
out whether it's marketing, testing, or engineering that has the
answer they need, but the important thing is they know specifically
what question to ask and whom to ask.

By the time a first draft comes out, the engineers and product 
owners have had to spend no or almost no time on the document, 
and what they see is this fleshed-out manual that is ready to
review, but has saved them tons of writing time. 

By the time a writer knows a product well and knows how to find the
specs, test machines, marketing requirements, and various people
involved, he/she needs almost no input from any single individual. 
I have been with companies where full product document sets have 
gone out with almost no input at all from engineering, no help from 
any kinds of engineering specs, and no review or signoff of the 
documents. Not ideal, but the point is, it
worked. The writers knew enough to produce all the product documentation
without using any of the developers' time. That made the value of the
technical writers very obvious.

The final deliverable, in my mind, can and should be as good as it would be 
if all those developers and marketing people and others had written
out all they thought should be in the doc, had great command of
the language, knew exactly how to organize it and make it look good,
knew how to make a good index, discovered it met needs they didn't
know it had...but most importantly, they didn't spend much of their
time making this happen. 

So you may be hired, as John Posada said, because of your
command of the English language, but I suspect the reason John is
appreciated at his jobs is because he does pretty much all the
things I've described above to produce a quality product 
and save a lot of time for the guys who would be doing this work otherwise.

 Krista

================================================
Krista Van Laan
Director of Technical Communications, Engineering   
VeriSign, Inc.  http://www.verisign.com
487 E. Middlefield Rd.    Mountain View, CA 94043    
tel: (650) 426-5158    fax: (650) 426-5195


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Order RoboHelp X3 in December and receive $100 mail in rebate, FREE WebHelp
Merge Module and the new RoboPDF - add powerful PDF output functionality
to RoboHelp X3. Order online today at http://www.ehelp.com/techwr-l

Check out SnagIt - The Screen Capture Standard!
Download a free 30-day trial from http://www.techsmith.com/rdr/txt/twr
Find out what all the other tech writers, including Dan, already know!

---
You are currently subscribed to techwr-l as:
archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit
http://www.raycomm.com/techwhirl/ for more resources and info.