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