Re: It shouldn't be that hard to write good doc, should it?

["Chuck Martin" <cm -at- writeforyou -dot- com>]

"John Cornellier" <cornellier1 -at- stavanger -dot- oilfield -dot- slb -dot- com> wrote in message
news:225725 -at- techwr-l -dot-  -dot-  -dot- 
>
> In the course of a discussion about Pogue's latest Missing Manual the
following question was posted on Slashdot:
> "I've often wondered why we don't see more books of this caliber hitting
the market. It shouldn't be that hard to write good documentation, should
it? What does it take?"
> Below is someone's reply:
> ======================================
> Well, first the fact that there are so few good manuals should tell you
something about how hard they are to write. Here are a few of the reasons
its hard:
>
> 1) Most technical writers are writers first and technical people second.
So they sometimes struggle to understand the complex technical subject
matter they are trying to explain. BTW, David Pogue is a clear exception to
this generalization.

Wrong. Many are. Most good ones aren't. (To be fair, some good ones are, and
have worked to close the gaping holes in their technical skills and
knowledge.)

>
> 2) Writing introductory manuals is particularly hard. By the time you are
well-versed enough in the subject matter you are something of an expert. Its
very difficult to remember which bits need explaining to someone who is not
as expert as you are now.

It's not "particularly" hard, but it's not like writing a magazine articles.
Well-trained technical writers are quite adept at it.

>
> 3) The audience for manuals is large and varied. What is too complex and
technical for one reader is too patronizing and long winded for the next.
Its almost impossible to write something that's pitched at a suitable level
for more than 2 readers.

So? Good technical writers know this. It was part of their training and is a
drumbeat mantra in the discipline.

>
> 4) Writing clear, concise, accurate English (or any other language) is
hard. If it were easy there'd be many more well-written manuals.

No harder (or easier) that writing clear, concise, accurate C, or SQP,
or....you get the picture. But you get what you pay for.

>
> 5) No-one buys a product because the manual is good, so there really isn't
a financial incentive for companies to hire those rare good technical
writers.

But they may not buy it again if the manual is bad.

And providing technical support to supplant a badly written manual is quite
costly for a company--unless the company charges for techncal support and
uses it as a profit center, inwhich case *there* is the incentive to not
care about documentation quality.

>
> Of course, some companies just don't try, which is abysmal. Sometimes you
see excellent manuals. But most are just mediocre. I agree, a big "thank
you" to the real artists like David Pogue who continue to provide excellent
manuals and books.
>
Many denizens of this list write very well, write documentation that is
clear and user focused. They get neither the recognition of an author who
writes a third-party book (which goes through a much more rigorous editing
process that most companies are willing to commit to internal manuals) nor
the money that some good third-party books earn as royalties. (Although in
most cases it ain't enough to make aliving.)

Anyone who expressed that "it shouldn't be that hard" to write a manual
clearly has no clue of (a) how much skill it takes to write well, and (b)
how complex and rigorous the discipline of Technical Communication is.

-- 
--
Chuck Martin
User Assistance & Experience Engineer
twriter "at" sonic "dot" net      www.writeforyou.com

"I see in your eyes the same fear that would take the heart of me. The day
may come when the courage of Men fail,  when we forsake our friends and
break all bonds of fellowship. But it is not this day! This day, we fight!"
                    - Aragorn

"All you have to decide is what to do with the time that is given you."
                    - Gandalf