No wonder GNOME (and linux?) doesn’t have very many ISVs. The platform really needs a new documentation system. Here’s why.

A couple weeks ago, while working on a gnome-vfs module for Chippy’s super-sexy tagging system, I noticed that gnome-python has no API documentation. No HTML, no docstrings, nothing. In order to find out a method signature, I had to look in the source code and decipher the python/C binding code.

Now, the python bindings are arguably somewhat further out in the gnome orbit. However, for an officially supported binding, this is pretty bad. The documentation for the C gnome-vfs API isn’t much better. When an ISV comes to gnome and takes a look at this, they’re going to run screaming. I know I did, and I’m willing 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. Setting up gtk-doc for a C module is a black art, full of copying strange build-system stuff and hours spent trying to figure out which XML files are auto-generated and which are safe to edit. If you’re lucky enough to be documenting something like gnome-python, all you have to do is write a bunch of docbook. Let me say it for the record: docbook is a total pain in the ass. I love the idea of using one source to generate HTML, pdf, etc all in one go. This is a well understood problem, and docbook is a great solution to it. Unfortunately, because docbook is such a pain to write, people aren’t doing it, and that’s the real problem.

I decided that because I was already taking the time to figure it out, I’d document it. gnome-vfs isn’t a huge API (and the python bindings are even smaller), yet it’s taking me at least two hours per object to get everything right.

The GNOME release team is requiring full API documentation for new modules, and that’s a step in the right direction from a policy standpoint. However, we need a lot of steps from a technical standpoint. gnome-vfs is pretty close to “fully documented” and yet completely impossible to use. Mono is doing something good here — anybody can edit API documentation, in a wiki-like manner; it’s not hard to find what to edit, and the commitment involved is minimal. I think if we got something similar across all of the GNOME platform (for every language), we might begin to see some real documentation. Writing API documentation isn’t hard. Writing API documentation using the current framework is a nightmare.

Tags: , , ,