Have you ever noticed how useless so much documentation is?
Tell you everything, except how to get to the window, in order to do the thing you want to do.
Unix Man Pages:
Tell you everything, except what you need to know: a simple example that works.
Documenation is sometimes completely erroneous, or leaves out very fundamental things, making successful installation or use impossible. See some of my other posts.
Installation documents over 150 pages long, and sometimes, entire online books with multiple chapters! Seem to be written by tech writers, who don’t use the product. Not DBAs. Often contain the word “requirement” dozens of times. Necessitates that you read, distill, and rewrite it, into a something short, what you really need to know.
Your Company’s Internal IT Documentation:
For the custom built, one of a kind, highly esoteric, internal company systems, no documentation at all. No wiki in the entire company, or the whole WWW. Of what scant documentation there is, the best was always written by someone who is no longer with the company.
Your HR Department:
Lots of thick documentation on policies, benefits, procedures, etc. Sometimes, you can talk to someone in HR. But with so much outsourced now, HR will often refer you to an 800 number for say, the health care provider.
Thoughts On Such Poor Documentation:
“I’m sorry I wrote such a long letter. I did not have the time to write a short one.” Quote attributed to a number of famous people.
The function of tech documentation is to communicate. Not be a sales tool. Or something to cover the corporation for legal liabilities.
Why is the communication so poor? Based on its documentation, how would you rate a company on it’s “communication skills”? And I don’t mean the advertising.
Why is there so much effort put into writing long documents that don’t tell us what we need to know? Is it just a make work project for the tech writers? Are the tech writers paid by the word? Do they even know what they are writing about? What if we based their salary and bonuses on how quickly 100 beginners could read the docs and successfully install and use a product?
Consider queuing theory and documenation. You can spend hours or days reading and deciphering poor docs. But finally only spend seconds, or minutes with the actual task. If the arrival rate is more than the service rate, an infinite queue develops. Then, the work is never caught up, or finished.
This is fast food culture. I don’t want to hunt it, I don’t want to kill it, I don’t want to cook it. I just want to consume and digest the correct information, now.
Mostly, I find blogs to be much better than a company’s internal documentation. Companies clearly have much room for improvement.
Please, let’s get it together!
BTW, for a good read, see what Stanford has available on early tech writing by Apple,
and Chris Espinosa on Rewriting the Apple II Manual
I never had an Apple II, but I’ll bet that manual was a lot better than what I’ve been reading lately.