Why documentation on GNU/Linux sucks
====================================
---
date: "2012-09-12"
---

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

[1]: http://www.reddit.com/r/archlinux/comments/zoffo/systemd_we_will_keep_making_it_the_distro_we_like/c66uu57

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.