Re: Quality of source material from Development

[Andrew Plato <intrepid_es -at- yahoo -dot- com>]

"Salan Sinclair" wrote...

> 1. Product type:
> This product is a command-line interface for networking appliances. Most
of
> the documentation is a list of commands, descriptions, syntax, defaults,
> acceptable values, etc. Since this information cannot be transferred
easily
> in interviews and is not available through other means, it seems
reasonable
> to expect complete and accurate source material. The value that tech
writers
> add is ensuring consistency in syntax and language, identifying
incomplete
> areas, adding usage instructions, turning everything into English, etc,
etc.

Get the source code, read it, figure out what the commands are. 

> 2. Product availability
> The product is not functional so testing and working with it is
impossible.
> Specs consist of about 1 page per 100 page of documentation that must be
> written. Most of the customer documentation must be delivered for review
> before the product is functional.

Everybody faces this problem. This isn't unique to your group. 

Why would your company deliver documentation to customers for a product
before it is functional? That makes no sense what so ever. Isn't there a
beta cycle? Testing?  I mean, I understand writing about something that
hasn't quite been put together yet, but releasing docs to the public
before there is a working product is totally inane. 

> 3. Volume of work expected per writer
> In this situation, there are two writers (including the Doc Mgr). They
are
> expected to produce 7 to 10 manuals for 7 to 10 products in 4 months,
and
> each manual has about 100 to 300 pages. It's not possible to have a tech
> writer become an expert on 4 or 5 products in that time period. Each
product
> is so distinct and complex that most developers do not understand what
each
> other is doing.

If writers focus on learning the core technologies, they can become expert
users. 

If they focus on commas, FrameMaker and fonts - no. They will likely be
lost in a sea of confusion and churn out crappy documentation. 

This is a case where style takes a back seat to substance. Focus 99.9% of
your energy on the substance of the documentation (content) and don't
worry about the layout, design, etc. In the end you'll have good content
that can be cleaned up later or cleaned up by a $18.00 an hour intern. 

> About the issue of being an expert user of your product, I think this is
an
> ideal that only works in environments where the volume of documentation
per
> writer, or the volume of product features per writer, is low.

Absolutely not. If you understand the technology your ability to crank out
material increases significantly. Once you hold the technical information
and concepts in your head and understand them, it is extremely easy to
document them. Consider a topic you know very well, such as a hobby or
political opinion. Think about how easy it is to explain your ideas about
this topic to friends/relatives. 

The same thing applies to technology. If you understand it, and understand
what it does, it becomes considerably easier to explain it to other
people. 

If you remain ignorant about the technologies, then yes, your ability to
crank out material is seriously hampered. 

In a sense you have entered into a perfect blame loop: you remain
technically ignorant because you have too much work to do, you have to
much work to do because you're technically ignorant.  

Therefore you have essentially two options: A) complain that you need more
writers; B) Learn the technologies so you can write more efficiently and
expediently. 

> For example, I was a lone writer working for a company with a suite of
about
> 10 products undergoing constant change and new products being developed
> every few months. As much as I wanted to, I could not afford to work
with
> the products at all, let alone become an expert on them, if I wanted the
> revised documentation to go out the door with the product. In that
> circumstance, unless developers produce written source material, the
tech
> writers produces less documentation. Another option is to have the tech
> writer produce "guesses" and let the developers to rework the guesses
for
> accuracy. In some cases, my wage was the same or higher than some
> developers, so it made sense financially to use their time if it made me
> more efficient. Hiring additional tech writers would be an obvious
solution,
> but not one within my control.

A good writer who understands the technologies is able to accurately
anticipate functionality and use and therefore isn't "guessing". Those
guesses are based on experience, knowledge, and a keen understanding of
what your company's products do.  

Lastly, engineers are not hired to write documentation, technical writers
are. 

Andrew Plato 


__________________________________________________
Do You Yahoo!?
Check out Yahoo! Shopping and Yahoo! Auctions for all of
your unique holiday gifts! Buy at http://shopping.yahoo.com
or bid at http://auctions.yahoo.com

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Collect Royalties, Not Rejection Letters! Tell us your rejection story when you 
submit your manuscript to iUniverse Nov. 6 -Dec. 15 and get five free copies of 
your book. What are you waiting for? http://www.iuniverse.com/media/techwr

Have you looked at the new content on TECHWR-L lately?
See http://www.raycomm.com/techwhirl/ and check it out.

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