15. Documentation, at large

Summer 2005, Alan Cox admitted in an interview that we have reasons indeed to be dismayed by the poor state of documentation of most of open source software. What is worse, this is unlikely to change: «I don't think anyone's going to do a grand initiative.»

As predicted, things have not changed since then. Currently, the best documentation on open-source software is The FreeBSD Handbook, and second-best is The OpenBSD FAQ.

Quality end-user Linux documentation is issued by Red Hat and by Novell, but this is often far from the quality of the old-style UNIX printed manuals. KDE and GNOME always ship with incomplete and obsolete help files (and pretty useless: thank you, I know how to read a text label, maybe I wanted for more), and Linux has gradually lost the classical respect for man pages, a long-time UNIX tradition.

For quality man pages, you need to go to the *BSD land.

Let's switch now from the end-user or the system administrator to the guy that should decide what Linux distro will your company buy and use. Is enough first-hand information available? You know, a few clicks away, as we are in a global Web world.

To our surprise, the major actors are deceiving in this department. Should you want to buy SLED, you can't find out what exactly comes with it! In other words: what are you paying for? Is it more than a plain desktop? I dare you to find an easy link to that. You have to go to the package list page to notice that the Samba server is included. Unfortunately, things are not any better with RHEL.

A conspiratorial theory would say that the lack of a proper documentation is made on purpose.

When you purposefully design software that is difficult to use, lacks documentation, and/or is nearly impossible to install and configure, you are doing so for creating the opportunities to sell support contracts and consulting services. When the beauty of the GUI is only skin-deep, here comes the big, fat support contract.

Leaving the conspiracy land, I bet both Novell and Red Hat suffer from the Microsoft-like arrogance: we are the #1, come and buy from us, you don't really need all those details. Our solution is what you want anyway, let's drop the technicalities. Or you can have one of our commercials call you.

Is it that hard to put a page with all the relevant info, in easy access? Or are the buyers deemed so stupid?

The pleasant surprise comes from the French Mandriva. Their Corporate Server 4 has a very practical specifications page, and the accompanying Product Sheet is the best product presentation I have seen in my whole life! All the relevant info you need to take a decision is there, in a good presentation, just the way you'd expect it to be. (Incidentally, it's a good server indeed.)

Fortunately, there is life outside North America too, contrary to the common belief.