api documentation (longish, rantish)



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.





[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]