Re: api documentation (longish, rantish)

[John Fleck <jfleck inkstain net>]

On Wed, 2003-03-05 at 21:30, Darryl Rees wrote:
> 
> Today I was trying to understand the bonoboui stuff. Came across this 
> introductory subtitle in "BonoboWidget — Simplified embedding of widgets 
> in Bonobo"...
> 
> "Bonobo component embedding for hydrocephalic imbeciles.
> Pure cane sugar."
> 
> While in my particular case the reader happily acknowledges a level of 
> imbecility, this kind of writing - while possibly providing a momentary 
> chuckle for the author and Superior Programmers in general -
> a) adds nothing to the understanding of the item in question
> b) would probably be offensive to anyone whose life has been touched by 
> hydrocephaly, and seems a bit out of place in a programming environment 
> that espouses tolerance and diversity and understanding of people with 
> particular handicaps (which I understand gnome/gtk to be)
> c) reeks of techno-arrogance, and

I rather have to agree with Darryl on this. I think it was Pat Costello
who wrote in the documentation style guide:

	There are few experiences more irritating for a user than
	documentation that says an action is easy or quick, when in fact 	the
user cannot complete the action.

It was meant in that specific context to user documentation, but I think
it applies to other kinds of documentation as well.

Cheers,
John
-- 
John Fleck
jfleck inkstain net (h) jfleck abqjournal com (w)
http://www.inkstain.net http://www.abqjournal.com

"Sometimes, a diner is all about the mac and cheese." 
  - Zippy the Pinhead