initial commit

1 files changed, 38 insertions, 0 deletions

diff --git a/public/poor-system-documentation.md b/public/poor-system-documentation.md
new file mode 100644
index 0000000..0c97e40
--- /dev/null
+++ b/public/poor-system-documentation.md
@@ -0,0 +1,38 @@
+Why documentation on GNU/Linux sucks
+====================================
+:copyright 2012 Luke Shumaker
+
+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.