diff options
Diffstat (limited to 'public/poor-system-documentation.html')
| -rw-r--r-- | public/poor-system-documentation.html | 53 |
1 files changed, 43 insertions, 10 deletions
diff --git a/public/poor-system-documentation.html b/public/poor-system-documentation.html index 452a4f8..2611856 100644 --- a/public/poor-system-documentation.html +++ b/public/poor-system-documentation.html @@ -2,24 +2,57 @@ <html lang="en"> <head> <meta charset="utf-8"> - <title>Why documentation on GNU/Linux sucks — Luke Shumaker</title> + <title>Why documentation on GNU/Linux sucks — Luke T. Shumaker</title> + <meta name="viewport" content="width=device-width, initial-scale=1"> <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 Shumaker</a> » <a href=/blog>blog</a> » poor-system-documentation</header> +<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> +<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> -<p>The content of this page is Copyright © 2012 <a href="mailto:lukeshu@sbcglobal.net">Luke Shumaker</a>.</p> -<p>This page is licensed under the <a href="https://creativecommons.org/licenses/by-sa/3.0/">CC BY-SA-3.0</a> license.</p> + <aside class="sponsor"><p>I'd love it if you <a class="em" + href="/sponsor/">sponsored me</a>. It will allow me to continue + <a class="em" href="/imworkingon/">my work</a> 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> |