The (or a) problem with Unix manpages

April 3, 2009

Unix has three sorts of manpages: excellent ones that clearly answer your questions, good ones that answer your questions if you read them carefully, and bad ones that aren't worth reading because they don't answer your questions (at least in a way that you can understand).

The first sort are rare and obvious when encountered, which means that when you read a manpage you are generally trying to guess whether you are dealing with the second sort or the third sort. The problem is that there are significantly more of the third sort than there are of the second sort, so people (myself included) are trained into aggressively skimming manpages instead of reading them carefully, because usually reading carefully doesn't actually help and just wastes your time.

And this is a problem because then you run into a manpage that actually does answer your questions, except you didn't bother to read it carefully so you didn't notice (if you are lucky, you notice later). This is usually at least a bit embarrassing.

(This actually generalizes to other documentation, but I think that Unix manpages are a large source of this sort of thing, partly because they aggregate together in one spot a lot of documentation from a lot of different people.)

Written on 03 April 2009.
« How to use Vixie cron to schedule at regular odd times
Why I don't expect ARM-based netbooks to be a success »

Page tools: View Source, Add Comment.
Search:
Login: Password:
Atom Syndication: Recent Comments.

Last modified: Fri Apr 3 18:31:54 2009
This dinky wiki is brought to you by the Insane Hackers Guild, Python sub-branch.