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.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.