A huge part of the usability of a distribution is the documentation provided. Documentation is needed not only for major system components (KDE, GCC, Gnome, GRUB2, X11, etc.) but for the minor components as well. Without proper documentation new users do not know where to find the information they need in order to get started using the tool, utility, window manager, desktop environment, etc. I was reading through some old articles on Linux Gazette and encountered an entry where a man abandoned Linux altogether for BSD. Why did he stop using Linux? He said it was because the structure of the Linux distribution he was using at the time (Fedora 5) rapidly changed when he attempted to upgrade (to Fedora 10). It appears one of the major reasons he didn’t pick up Gentoo was because of lacking documentation.

Here was some of what he wrote:

I went to “upgrade” from Fedora 5 to 10. I had had no problems going from 2 to 5. But 10 was another matter altogether. Just out of the blue, the names of disks changed. My Fedora 5 (which I’m still running) refers to /dev/hda. Fedora 10 decided to call it /dev/sda. Perhaps I’m naive, but I don’t expect gratuitous changes like that from FreeBSD.

Every new rev of emacs introduces incompatible changes.

I don’t turn on a computer so that I can learn new tricks. Not those sorts of new tricks. One of my computers has to be bread and butter, unchanging from day to day. I don’t want to spend my time learning somebody’s idea of a better editor. It’s an editor! I just want the one I was using yesterday. Not better, not worse, not different. I DO NOT NOT NOT WANT ANY NEW FEATURES. If you want to do that, here’s an idea: deliver emacs-classic and new-emacs. Put all your changes into new-emacs and leave emacs-classic as it is. Coke, anyone?

Every time they make it better, they make it worse. And that goes for Solitaire and aspell and … the list goes on.

And these gratuitous changes come at a price. I used to run Slackware on a 16MB 100 Mhz Pentium 1. I was trying to install Fedora 10 on a spare machine and getting intermittent problems. After a while, they went away. It wasn’t till much later that I twigged. I happened to notice in some documentation a declaration that Fedora would no longer run in 256MB; it needed a minimum of 512MB. While fiddling with my machine, I’d added some extra memory from another (dead) machine.

I decided I didn’t like the notion of releases. Especially since Fedora is committed to producing a new release every year. That wouldn’t be a disaster if there were any respect for backward compatibility. But there’s not. There’s the tacit assumption that the newest and latest will necessarily be the best. For everyone.

I asked around. Gentoo and Arch Linux were suggested as solutions to my problems. I was given to understand that they are more into the idea of just allowing the system to update organically. If you need a latter version of application X, just go get it. They had gone away from the idea of discrete releases. Sure, if you wanted to switch sects, you’d get the latest release. But you would not be penalised for running an old release. Maybe I misunderstood.

I tried Arch but found it difficult to get information. The idea is possibly ok, but I really felt isolated.

LG readers may be aware of my History files, records of what I do on the machines I administer. Here’s a note from the day I installed FreeBSD:

`The documentation is excellent, by the way.`

And that probably says it all. I dare say I encountered the same problems with FreeBSD that I did with Arch. But, with FreeBSD I was able to get answers.

The above giant block quote is from http://linuxgazette.net/186/grebler1.html

One of the things I’ve been trying to do lately (in my free time, while I’m waiting for packages to compile, etc) is add documentation to http://wiki.gentoo.org. I am probably one of the least knowledgeable editors on the wiki, but I can still verify facts by finding incorrect content, add new content for things I do know about, and ask other people (IRC, friends, etc) for better information then record it on the wiki.

I recently (via e-mail) offered my assistance to the QT project. They said they needed someone to help with that role, and I will be more than happy to contribute to another project that will be useful to the community.

That’s all for now…

Maffblaster