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.