RE: Quality of source material from Development

[Salan Sinclair <salansinclair -at- shaw -dot- ca>]

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

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

Salan: Could do, but far fewer manuals would get produced because of the
time required to figure out the code.

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

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

Salan: I said delivered "for review". Yes, there is a beta. The books are
expected to be complete and accurate for delivery to customers at beta. And,
if you have 2 writers and 10 books, some books have to be done *before*
beta. It's simply a matter of days verses pages.
We're talking about a development team of about 40 developers working for
year to create a new product, and 2 tech writers working for 4 months to
document the entire thing.

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

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

Salan: Please don't simply assume that I care only about commas and design.
That is not the issue. I have taken several programming courses. I call
myself a 'wanna-be programmer' at times. I read about every subject I have
to document. I want to know everything I can. But we're talking about a
highly complex product and a highly technical audience. It would easily take
a "technical" technical writer 2 months to become proficient in each
product, and there are 5 of them for each writer.


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

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

Salan: Same as my previous comment.

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

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

Salan: Let's test your statements against specifics. The product I was a
lone writer for included  real-time software applications written in Pascal
and C++ communicating via radio to dispatch mobile devices using Windows CE
and firmware. At the core were databases created in FoxPro, Oracle, and SQL
Server. It had 5 or so client applications written in Access and VB to
access the databases for reporting, inquiries, and data editing. And that
was just the core system, not the add-on modules designed for specific
customers. The documentation had to tell people how to install and use about
10 products in various settings on various platforms. It also had to tell
people how to install, configure, upgrade, maintain, backup and recover all
three types of databases. The new Development Manager, with a PH.D, took a
year and half before he could say he actually understood the entire product.
I know some VBA and VB, can create Access databases and forms, understand a
fair bit about database design, and am "familiar" with all of the
technologies listed. I was learning more everyday. I was gradually learning
Crystal Reports, SQL, and Windows NT server, etc, etc, but I was usually too
busy to make much progress. Each release, which occurred every few months,
would require a new document or help system for a new product, as well as
updates to about 10 documents in two versions (Oracle and SQL server). There
is no way I could get information in time by researching the code.
I often agree with your posts, Andrew. I just not so sure that what you are
saying works in low-staffed situations with highly complex (or let's say,
diverse) products, especially if a writer is only there for 6 months or a
year.



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