api documentation (longish, rantish)

[Darryl Rees <rees netnam vn>]

Firstly (so I can pass of this whine as constructive criticism) I'd like 
to say that some of the core gtkdoc documentation is getting pretty darn 
good, presented in a logical order with gentle tutorial style intro etc. 
The introductory stuff for the core glib/gtk type libraries is really 
pretty good - for most folk its probably all they need to get started 
programming in gtk without need for tutorials/books/etc. Great stuff 
(congratulatory pat on the back to authors).


Other stuff, as everybody knows, needs more work.

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
d) does not add to the 'professionalism and polish' of the docs (which 
is *not* to say that humour is to be avoided in technical documentation, 
if it is tasteful and does not detract from the clarity of the information).

To be honest the bonobo/bonoboui docs lack an overall conceptual 
framework and have a bit of a 'this stuff is so simple, all you need is 
the api reference' kind of feel. Which for this imbecile is a slow way 
to get into using the stuff, even with some of the tutorials available 
on the web. Writing technical docs is an art, requiring constant 
attention to the lowest common denominator while remaining concise. (Why 
for instance would I even want to wrap basic widgets in bonobo? Or use 
such bonoboized widgets? Where is the tradeoff?...). Sorry - for a 
newbie, using bonobo is not trivially simple, far from it (atleast, to 
newbie without experience in component-oriented programming).

Sounds like a rant, but I (think I) am trying to be genuinely constructive.

Regards,
Darryl.