Why documentation on GNU/Linux sucks

This is based on a post on reddit, published on 2012-09-12.

The documentation situation on GNU/Linux based operating systems is right now a mess. In the world of documentation, there are basically 3 camps, the “UNIX” camp, the “GNU” camp, and the “GNU/Linux” camp.

The UNIX camp is the man page camp, they have quality, terse but informative man pages, on everything, including the system’s design and all system files. If it was up to the UNIX camp, man grub.cfg, man grub.d, and man grub-mkconfig_lib would exist and actually be helpful. The man page would either include inline examples, or point you to a directory. If I were to print off all of the man pages, it would actually be a useful manual for the system.

Then GNU camp is the info camp. They basically thought that each piece of software was more complex than a man page could handle. They essentially think that some individual pieces software warrant a book. So, they developed the info system. The info pages are usually quite high quality, but are very long, and a pain if you just want a quick look. The info system can generate good HTML (and PDF, etc.) documentation. But the standard info is awkward as hell to use for non-Emacs users.

Then we have the “GNU/Linux” camp, they use GNU software, but want to use man pages. This means that we get low-quality man pages for GNU software, and then we don’t have a good baseline for documentation, developers each try to create their own. The documentation that gets written is frequently either low-quality, or non-standard. A lot of man pages are auto-generated from --help output or info pages, meaning they are either not helpful, or overly verbose with low information density. This camp gets the worst of both worlds, and a few problems of its own.