Mark Wilson's Blog

Open software and documentation

One of the aspects of free or open software that has yet to live up to the expectations set by commercial enterprises is documentation. You might notice, if you browse sites for open software, that many of them ask for help documenting their efforts. The need for a team of technical writers, or at least for geeks who can speak English, can become rapidly apparent once you delve into these products.

Sometimes, the documentation is just nonexistent. You find yourself confounded by a cursory outline for help, filled with "this section coming later" notes and little else. Other times, as with Debian and many other flavors of Linux, the documentation is haphazardly organized -- some of it in manuals, some of it in HOWTOs, some of it scattered to the four winds.

Lately, though, I find myself dealing frequently with open projects, particularly APIs, that have had the surface layer of functionality well-documented, and little else; apparently the philosophy is that a well-written introduction will suffice for beginners, and anyone who wants more advanced functionality will struggle through the process of tracking it down or working it out for themselves.

I mentioned in my last post that I've been underwhelmed by XUL; part of that is that it doesn't seem to be structured in a terribly programmer-friendly fashion, part of it is that it seems prone to unpredictable, fractious behavior, but another huge part of it is that the documentation is so... lacking. XUL Planet is about the best thing out there, and it's frequently incomplete, misleading, or obtuse. The best thing is probably to grab an O'Reilly book on the Mozilla Framework, but when the best advice one frequently finds on message boards and the like is, "Disassemble other people's extensions and see what their code looks like," it's somewhat disheartening. (I shouldn't complain too loudly about Mozilla, though; Firefox's SessionSaver extension just saved me this entry and a bunch of grief when I did something rather stupid with my computer just now.)

My summer work involves using GTK to build a UI for a Linux program. GTK has a tutorial for most of the basic widgets, and you can figure out some of the others from the API documentation. However, it's not really enough to say, "This is what this function does." I need to know how to use these functions and objects in concert to achieve my goals. I paused to write this entry because, for the nth time since I started this project, I found myself resorting to Google in the hopes that someone, somewhere, had already taken the time to work my latest problem out for themselves, and had been good enough to post their discoveries to a message board. Since I'm doing something that isn't easily achieved with standard widgets, this has become an ongoing, somewhat irritating process.

I'm sure that at some point we'll have good, thorough documentation for all our open-source stuff (I marvel at how far Linux has come in a few short years), but in the meantime its lack is rather sorely felt by some of us.

Addendum: Speaking of coming far, I just switched into KDE for a moment -- the last time I tried it was in early high school, I think, so it would have been fairly young -- and... Wow. I hate to say this, because I've gotten very attached to GNOME, but at first glance it looks like KDE has, in many ways, surpassed the competition.