Linux hurts my brain.

Linux should by a dynamic operating system with the best documentation, continually improving interfaces, and a generally world class reputation. Instead, Linux gets the progressive blindness of too many people resisting even minor changes. These continuous annoyances lead to the death of a million cuts.

MAN pages

These are the original documentation of Linux, back when online documentation was rarely heard from. The documentation continues to have a Spartan flavor, as in “We Spartans Send Our Young Alone into the Cold”. There are seldom examples, rarely useful information, no hyperlinks, and only cursory explanations. For example, I looked up the program “uname” when I was reading a script.

“uname” prints out system information. There are odd conventions as to what is printed, which are undocumented. For example, “uname -m” prints the machine name. On PCs, this machine name might be “i386, i486, i586, i686 (for Intel processors)” or “x86_64″ for AMD 64 bit processors. This information is not printed in the man pages; it’s just errata that people are supposed to know. The option “-p” to print the processor type just prints “unknown”, according to some other obscure convention. Except for SunOS 5.x where it prints the processor type. This errata is not on-line, but found in various shell scripts and dead tree books.

The manual has no particular formatting, examples, or hyperlinks. It does helpfully suggest using the newer program “info”. That program shows the man page again with no formatting, examples, or hyperlinks.

Now Linux faithful will quickly point out that this information doesn’t belong in the manual, that some manual pages have more information. For example, “man bash” gives a book of about 3200 lines covering shell programming, details about piping commands, a half dozen built-in commands, and no examples. Meanwhile, everyone else uses some sort of mark-up language, wiki, or such. In practice, most users use Internet sources for information.

Wait a minute! This simple command, “uname” is used on every system everywhere! Thousands of new people use it every day. Why could there this horrible lack of documentation on such a simple command? Why could I have picked any of a hundred commands to criticize?

Just one cut in the death of a million cuts. I am not of the Linux Spartan priesthood; I want everything to work the first time, every time, and be understandable by a five year old. If a five year old cannot understand, the five year old needs to know what is needed to understand.