1. The problem
  2. Case study: the Arch Package Manager
  3. Why is this a thing?
  4. How to fix it

The problem

Googling a problem often returns a forum thread that runs like so:

Original Poster: I have this problem.
First Responder: This is in the manual. Why can't you just read the manual?

I'm usually quite annoyed at First Responder, because I have the same problem as OP, and First Responder isn't helping. I find this extra annoying because I do read the manual first, and I had to go online for the answer too. The answer First Responder should be getting is: because the manual is huge and badly written.

Now I must admit that "badly" is an imprecise term. man pages are usually concise, thorough, and nicely formatted. These are not hallmarks of bad writing.

The problem is that software manuals are commonly written as references, not as explanations.

A reference is meant to be searchable above all things. Ideas are organized alphabetically, and broken into broad categories if you are lucky.

An explanation, on the other hand, is meant to build layers of understanding. Concepts are placed such that sections build upon each other, and the reader is never left saying "you've used a lot of big words there, and I have no idea what any of them mean".

2022-06-25: Adler puts it quite succinctly. "[To use a reference work] You must know what you want to know; you must know in what reference work to find it; you must know how to find it in the reference work; and you must know that it is considered knowable by the authors or compilers of the book. […] Reference books are useless to people who know nothing. They are not guides to the perplexed."1

Case study: the Arch Package Manager

For instance, the Arch Linux package manager (pacman) is documented in three different places:

  1. the commandline help, accesible through pacman -h
  2. the pacman(8) man page
  3. the Arch wiki, pacman page

The commandline help is a terse list of supported operations and one-line descriptions of options.

The man page obeys the same structure, but it provides a full paragraph of explanation for each item, and it documents pacman's configuration file.

The wiki page is a living source of documentation, meant to be read roughly top-to-bottom. It is split into four headers: Usage, Configuration, Troubleshooting, and See also. It should speak volumes that the Usage section starts by disclaiming that this is not a comprehensive resource, that the manual page is, points to an online copy of the manual page, and immediately after explains what a package is.

Annoyingly, the commandline help does not mention the existence of the man page, which in turn does not mention the existence of the wiki page. The reverse is true, which is better than nothing, but is still inadequate.

Why is this a thing?

The rationale for this state of affairs is obvious enough: the man page tells you about the commandline help because it can guarantee it exists. As long as pacman is installed, you will have access to the commandline help.

The reverse is not true. It is perfectly possible to have pacman installed without its man pages, or even the man utility at all. This goes doubly so for the wiki page: nothing you can do from your computer can guarantee an online resource will be available. Thus, since it can make no guarantees, pacman -h stays silent about the other docs.

While this reasoning does makes sense, it is absolutely backwards from a usability standpoint.

The only docs a user is guaranteed to have explain none of the core terms (package, group, meta package, dependency), don't even mention the configuration file, and provide no pointers to further resources. A user that does not already know what is what, or where to find more information, is stuck with going online and getting told to RTFM by First Responder.

How to fix it

Here's a cheap fix: accept broken pointers. The man page may not be available, but it doesn't matter, tell the user about it anyway. The wiki may not be available, but it doesn't matter, tell the user about it anyway. If the user needs to read something to understand how to use your software, then it isn't optional and it's your job to provide it.

The better solution is to make sure your help system tells your users everything they need to know in order to use your software. This is definitely an achievable goal: git-help is a case study in good documentation.

  1. Adler, Mortimer Jerome, and Charles Van Doren. How to Read a Book: The Classic Guide to Intelligent Reading. New York: Touchstone, 2011. ISBN 978-1-4391-4483-1. Original publication: How to Read a Book: The Art of Getting a Liberal Education. Simon and Schuster, 1940. OCLC 822771595. ch12, "How to use reference books". ↩