I’m a Linux user, I love Linux. The laptop I’m writing this on runs Mepis, the server this blog resides on runs CentOS, I am changing my business over to Linux servers. I believe it is at once more stable, more secure and less expensive than the majority OS and I extol its virtues every chance I get.
However, now I wish to bring up a short coming: documentation. There is not enough procedural based documentation for Linux, its all based on how stuff works. For example yesterday I obtained a certificate from CAcert for my web server. There was documentation at CAcert about how to submit a request for a certificate and how to generate a CSR using OpenSSL. But then the documentation stopped. What do you do with the certificate after you’ve got it? How do you configure Apache to use the certificate. The Windows documentation on CAcert continued for pages with screen shots showing you exactly how to configure IIS to use your new certificate. It was not even immediately clear what I needed to configure to use the certificate with Linux. Was I to configure Apache? OpenSSL? Something else?
The Apache documentation covered all of the aspects of using OpenSSL. But that was the problem. Did I use apache_ssl or mod_ssl? Why did I need or want to know the theory about how it worked? Why did I need to understand how private and public keys work? What I want is to get and install a digital certificate for my server so I can use SSL.
This seems to be downfall of most Linux/OSS apps, even basic apps like the locate command. I just want to know how to find a file on my system not how to use locate. I want to run a mail server, I do not want to understand the ins and outs of Sendmail or Qmail or Exim or whatever. I just want to filter spam on my server not understand how Procmail integrates with Spam Assassin and Cyrus IMAP. Its not that this stuff is hard, that’s not the point. Its that there is too much documentation that says,”this is how application foo works and what commands it accepts” and too little documentation that says, “this is how you accomplish X”. At the end of the day I am running computers to accomplish other ends, not just to run computers, and I don’t care how they work just that I can make them do what I want.
But you may say that knowing how they work is the same as making them do what you want, the two are inextricably intertwined. Certainly you are correct at the programming level, but that’s why programs are written, so that people who don’t know how to make a computer print a list of their friends addresses on the screen or send an email can do so. But programs often substitute their own complexity for the underlying complexity of the computer and the user is no better off if he does not know how to make your program work than he would be if he had to type in all the commands in assembly language. In short, he still can’t get the computer to do what he wants done, which was the original reason he got the computer.
I could argue for more user friendly programming, but I’m not, not in this article. What I am arguing for is more procedurally based documentation. Consider the man page for the cp command. It tells you every command and option that the command cp takes. But suppose you did not know anything about cp and you wished to copy the contents of a directory (including all of its subdirectories) to another, but only if the versions of the files were newer than those in the target directory. Could you figure out how to do that from the man page. The answer is probably not (I think the answer is cp -r -u /copy/from /copy/to , but I’m not entirely sure). The point is that “how stuff works” style documentation is the standard for Linux when what we need is “how to get stuff done” style documentation.
You might say, “Alright, its open source, write some yourself.” Thank you very much, I will. I’ve written some like tips on upgrading to Postnuke .075 and how to get rid of the KDE dragon and other equally scintillating stuff, I’m resolved to do more. But my efforts alone will not be enough. Everyone who writes documentation for a Linux/OSS app needs to consider the possibility that there are people out there who don’t care about how the application works, they just want to filter spam or copy files or whatever their own ends are apart from running a computer.