Fri Jun 19 07:39:43 BST 2009
In the world of open source software, producing a program for the world to use is as simple as hacking some code together and sticking it on a website somewhere. Right ?
This is something I think too many projects get wrong: to assume that the code is all you need is incorrect, certainly for the end user. What is really required is documentation. I was particularly pleased, for example, to see the Offline IMAP project webpage -- it's a great example of what good documentation should look like: concise, easily navigated and informative. In the first two paragraphs on the front page we are told what Offline IMAP is and the problems it solves, its salient features and use cases, and what environments it will work in. Brilliant. Contrast that, for example, with the LTTng site, which hits us first with LTTng news - something the newcomer is frankly unlikely to care about, and follows that up (modulo some searching on the part of the user) with a description of LTTng which is littered with domain-specific technical terms, and a manual which doesn't fully document the software and is partially outdated. The impact of this is non-trivial: when I tried to install and run LTTng for an (admittedly rather old) 2.6.17 kernel earlier this year I spent half a day fruitlessly faffing about just trying to get the software installed and running before giving up in frustration. Given that I, as a software engineer used to working with the Linux kernel, am pretty much LTTng's target audience that's rather a sad indictment.
One of the most frustrating things about a poorly documented project, in my view, is that it sells short the efforts of the developers of that project. Their efforts and craftsmanship in creating their software are all in vain if nobody actually uses it. In some cases it seems like many hours of developer effort is being effectively wasted for want of a much smaller outlay on actually writing some instructions for use. LTTng, for example, is certainly a finer engineering effort than its documentation would have you believe, but there is no way for us to know this, short of a large time investment into getting the software working and figuring out how to use it under our own steam. How many people have that amount of time to spend on one project ? How many have the patience ?
Sometimes a good way to think about a concept is in terms of extremes; so here's a final thought. A project feature which is not documented is a bug. This is a concept many software engineers already use, albeit in jest, e.g. "That hang isn't a bug - it's an undocumented feature!", but flip it on its head and it has an interesting resonance. If a bug is simply unexpected behaviour, then anything you haven't documented must be a bug. After all, if it isn't in the manual, how can your users reasonably expect it ?