Not Only That But..
An associate referred me to your article with the comment
"Verity Bots is A Goddess" After reading it I replied
"We got anything better than goddess? Shorter hours, better wages? St. Swithin's day off with pay?"
As a professional in Knowledge Management, I'd like to add some remarks on *how* lousy documentation comes into being.
Not to defend Mr. Chen. I looked over his contributions and he is being a snot. This is a function of allowing programmers who actually sit in the development meetings to write/publish anything whatever. They are under the delusion that everyone knows what they think they know. (The gap between what they think they know and what is actually going on would make the grand canyon look like a hole in your sock).
Having met, worked with, under, and, finally, over the Mr. Chens of this world, I have also noticed that they are inordinatly fond of the notion of "intuitive"--going so far as to coin linguistic abominations such as "unintuitive" to describe things that they don't understand.
Anyway back to documentation creation--If a company has tech pubs departmet, team, group, coven, or whatever collective noun applies, a writer/editor is given the unenviable task of prying information out of the likes of Mr. Chen (Actually, its not so much getting them to tell you things. Its getting them to stop, before they explain all the way back to the phlogisten theory of light.) After a while the writer/editor applies various forms of torture to the raw information (including the removal of material the source expert think is humorous) and comes up with a variety of documents to support working with the API, including description, purpose, examples of use, and associated error codes and what to do about them. In addition the writer/editor does a little testing, checks with SQA to make sure that information is reasonably sound.
Someone quite senior to Mr Chen in his deparment reviews the document. And realizes that by letting application programmers run amuck at that level of the underlying code will create opportunites galore to crash the system, create security hazards, compromise patents, open legal liability, and generally bring about the end of civilization as we know it. But they have to expose the API otherwise no one out there will make applications they can appropriate for a 10th of the cost it would cost to develop them in-house.
So what to do? Simple, send back the nice documentation with a curt note to remove all references to Purpose, Use and most of the Examples.
Thus do the Mr. Chens serenely (and delusionally) beleive that the API is both intuitive and well-documented; the API is made safe for democracy; and Technical Publications learns to keep extremly meticulous records about who told them to do what and when because they keep getting blamed by Tout Le Monde for documentation that doesn't tell anyone anything.
Excuse me, now I must go and see to it that the "Problem Resolution" sections in a chapter on Error Messages are deleted.