No won­der GNOME (and linux?) doesn’t have very many ISVs. The plat­form really needs a new doc­u­men­ta­tion sys­tem. Here’s why.

A cou­ple weeks ago, while work­ing on a gnome-vfs mod­ule for Chippy’s super-sexy tag­ging sys­tem, I noticed that gnome-python has no API doc­u­men­ta­tion. No HTML, no doc­strings, noth­ing. In order to find out a method sig­na­ture, I had to look in the source code and deci­pher the python/C bind­ing code.

Now, the python bind­ings are arguably some­what fur­ther out in the gnome orbit. How­ever, for an offi­cially sup­ported bind­ing, this is pretty bad. The doc­u­men­ta­tion for the C gnome-vfs API isn’t much bet­ter. When an ISV comes to gnome and takes a look at this, they’re going to run scream­ing. I know I did, and I’m will­ing to put up with a lot more of this crap because I know how hard it is.

How hard it is. Think about that for a moment. Set­ting up gtk-doc for a C mod­ule is a black art, full of copy­ing strange build-system stuff and hours spent try­ing to fig­ure out which XML files are auto-generated and which are safe to edit. If you’re lucky enough to be doc­u­ment­ing some­thing like gnome-python, all you have to do is write a bunch of doc­book. Let me say it for the record: doc­book is a total pain in the ass. I love the idea of using one source to gen­er­ate HTML, pdf, etc all in one go. This is a well under­stood prob­lem, and doc­book is a great solu­tion to it. Unfor­tu­nately, because doc­book is such a pain to write, peo­ple aren’t doing it, and that’s the real problem.

I decided that because I was already tak­ing the time to fig­ure it out, I’d doc­u­ment it. gnome-vfs isn’t a huge API (and the python bind­ings are even smaller), yet it’s tak­ing me at least two hours per object to get every­thing right.

The GNOME release team is requir­ing full API doc­u­men­ta­tion for new mod­ules, and that’s a step in the right direc­tion from a pol­icy stand­point. How­ever, we need a lot of steps from a tech­ni­cal stand­point. gnome-vfs is pretty close to “fully doc­u­mented” and yet com­pletely impos­si­ble to use. Mono is doing some­thing good here — any­body can edit API doc­u­men­ta­tion, in a wiki-like man­ner; it’s not hard to find what to edit, and the com­mit­ment involved is min­i­mal. I think if we got some­thing sim­i­lar across all of the GNOME plat­form (for every lan­guage), we might begin to see some real doc­u­men­ta­tion. Writ­ing API doc­u­men­ta­tion isn’t hard. Writ­ing API doc­u­men­ta­tion using the cur­rent frame­work is a nightmare.

Tags: documentation, gnome, rant, software