summaryrefslogtreecommitdiff
path: root/public/poor-system-documentation.html
blob: 7d6088c75d38d7f32cbc5b266834421ba06aafd2 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Why documentation on GNU/Linux sucks — Luke T. Shumaker</title>
  <link rel="stylesheet" href="assets/style.css">
  <link rel="alternate" type="application/atom+xml" href="./index.atom" name="web log entries"/>
</head>
<body>
<header><a href="/">Luke T. Shumaker</a> » <a href=/blog>blog</a> » poor-system-documentation</header>
<article>
<h1 id="why-documentation-on-gnulinux-sucks">Why documentation on
GNU/Linux sucks</h1>
<p>This is based on a post on <a
href="http://www.reddit.com/r/archlinux/comments/zoffo/systemd_we_will_keep_making_it_the_distro_we_like/c66uu57">reddit</a>,
published on 2012-09-12.</p>
<p>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.</p>
<p>The UNIX camp is the <code>man</code> page camp, they have quality,
terse but informative man pages, on <em>everything</em>, including the
system’s design and all system files. If it was up to the UNIX camp,
<code>man grub.cfg</code>, <code>man grub.d</code>, and
<code>man grub-mkconfig_lib</code> 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.</p>
<p>Then GNU camp is the <code>info</code> 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 <code>info</code> system. The
info pages are usually quite high quality, but are very long, and a pain
if you just want a quick look. The <code>info</code> system can generate
good HTML (and PDF, etc.) documentation. But the standard
<code>info</code> is awkward as hell to use for non-Emacs users.</p>
<p>Then we have the “GNU/Linux” camp, they use GNU software, but want to
use <code>man</code> 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
<code>--help</code> 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.</p>

</article>
<footer>
  <aside class="sponsor"><p>I'd love it if you <a class="em"
      href="/sponsor/">sponsored me</a>.  It will allow me to continue
      my work on the GNU/Linux ecosystem.  Thanks!</p></aside>

<p>The content of this page is Copyright © 2012 <a href="mailto:lukeshu@lukeshu.com">Luke T. Shumaker</a>.</p>
<p>This page is licensed under the <a href="https://creativecommons.org/licenses/by-sa/4.0/">CC BY-SA 4.0</a> license.</p>
</footer>
</body>
</html>