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

[John Cornellier <cornellier1 -at- stavanger -dot- oilfield -dot- slb -dot- com>]

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.

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.

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.

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

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.

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.