A few more thoughts I’ve had on the developer documentation subject:
Gnome documentation tends to dive into advanced details upfront
(e.g. autoconf, building from CVS, low-level glib and gtk details,
popt, gettext and other i18n stuff, etc.) This is the stuff given to
beginners. Thus, the subconcious message is that you have to master
all this stuff to get started. If one has to master these details to
get started, what must one master to actually be able to write
documentation? …Is it any wonder that few have been willing to
write documentation? Also, is it any wonder that new developers get
discouraged? (The thought is “If these are the basics, how can I
possible master the intermediate and advanced details?”, not
understanding that they were thrown to the advanced details already)
Here’s one of my favorite tidbits. When I was learning, I heard about
the “libbonobo” library. Curious, I wanted to know what it was and
found a description very similar to the following one from
http://developer.gnome.org/doc/API:
Bonobo is the component object model of the GNOME (Gnu Network
Object Model Environments) project (it is also a monkey — see
Resources). Bonobo provides a COM-like model, using CORBA as a
location-transparent transport.
That was so helpful. What in the world is CORBA and COM? A year or
two ago, I literally tried to read up on those things for a couple
hours and still didn’t have a clue what libbonobo was. Yeah,
I’m stupid and I should have been able to figure it out in much less
time (or just bug people more on IRC or the mailing lists) but
that doesn’t change the fact that it is a problem. Here’s another:
libXML is a powerful and feature complete XML handling library.
Really? I would have never guessed. So what’s XML? (That’s
rhetorical, I do know the answer now and have written my own
overview of Gnome and Related libraries.