warning

Does Open Source Documentation Suck?

Two years ago when I started learning Linux, the most irritating thing was the lack of documentation. My UNIX gurus assured me that the man pages were enough documentation for anyone man enough to read them. But how does one install Real Player on Linux? How do you kill a process that doesn't go away with the kill command? And how do you get that $*$&$#*(# modem to dial the internet?

Two years later, my complaints have really died away. The Linux Documentation project has regularly been putting out Linux Manuals using the best documentation techniques available. It includes classic guides like the venerable Linux Network Administrator's Guide and Linux Administration Made Easy . There are some great HOW-to's and more importantly a top level index to Linux documentation , a and a Linux hardware compatibility forum. Most recently, a South African writer, Paul Sheer, has written the definitive Linux guide,the Rute User's Tutorial and Exposition The KDE and Gnome desktops have a fair amount of help, and Red Hat even includes HOW-TO's along with the system. At this point, the linux distributions are not really worse than the Microsoft Knowledge Base, a gargantuan search engine that never seems to provide the information you need. In fact, I most often find the correct MS Knowledge Base link by consulting the google groups . But this is pretty much where Linux users are trolling for answers.

As a technical writer colleague once pointed out to me, system-oriented documentation is fairly useless for those who don't understand the system in the first place. The How-To's are great and very complete, but they have two problems. First, they give too much information, leaving it for the reader to find the information relevant to him or her. Second, Linux faces a unique problem with regard to installation procedures. Since Linux software is basically free, most distributions usually install binary RPM packages for hundreds of open source programs. Sounds great, right?

The problem is that most open source software is updated fairly quickly, and that web documentation may not be relevant to the rpm installed on your system. Apache is a great example. Red Hat installs Apache automatically, but if you want DSO support or want to add another module dynamically (such as Php), you basically need to uninstall and compile the whole thing from source. While I generally haven't experienced many problems with doing that (it's easier than one would think), it is sometimes maddening to remember what upgrades you have already performed. It's also difficult finding directions specific to your distribution's RPM, such as libraries or compilers it needs to run.

For better or for worse, Microsoft's installations are fairly easy to do and don't usually mess up. That's because Windows software is more likely to be "black box," (allowing little ability to view the code directly). It's also more likely to be commercial and require licensing fees. Since OS and library upgrades come from Microsoft, it is fairly easy to find what you need to install. On the other hand, a typical version of Windows doesn't come with 10 different compilers, and that limits the platforms for programs in a Windows environment.

In development, formal documentation tends to lag behind development and isn't regularly updated. One positive development in the open source world is "interactive documentation." This refers to documentation where readers can add comments on the bottom of each web page. Here is an example from the Postgresql manual and the mysql manual. Not only are these documents constantly evolving, they invite the user to add his or her own experiences and difficulties. Such an interactive style of documentation, if properly implemented, takes much of the burden off the people doing the documentation and allows the documentation to focus less on systems than on people.