Thursday 5 November 2015

One manpage a day...

I first heard of this in a Google Doc, which was linked to by a wiki page in Swedish I was shown by someone on IRC. Unfortunately, I can't find any of these links anymore...

Documentation in some areas of Ubuntu is sorely lacking. Have you ever ran into a case where you tried to use this shiny new program, or do a one-shot use of some obscure old thing, without managing to find any documentation for it?

One of the first things we're trained to do as Unix users is to look for the manpage for a command. Many packages are missing manpages. Any missing manpage can be considered as a bug for a program, since it means we're missing documentation for it, and people who might use that software would have no idea how to use it, or perhaps would have no idea how to use it effectively, how to make the most of the available features.

Two such examples I found on my own system, looking at the contents of /usr/bin are ubuntu-drivers (pkg:ubuntu-drivers-common) and ubuntu-support-status (pkg:update-manager-core). I'm not trying to point fingers at anything (in fact, I've contributed to ubuntu-drivers before, too), just showing that examples of commands missing a manpage can be trivially found.

Let's all try to find one manpage to write a day, and we'll quickly improve the state of documentation in Ubuntu by a noticeable amount. Try to write the manpage, but otherwise at least file a bug for the fact that it's missing, against the package that contains that binary.

For convenience; here's a command to get a list of commands that man couldn't find a manpage for in /usr/bin (there may well be a better way to do this, and it will list some false-positives):

ls -1 --file-type /usr/bin | sed 's/@//' | LC_ALL=C xargs -n1 man -w >/dev/null

Then, to find out which package contains that binary, use dpkg -S with the name of the command.

Thanks to Stefan Bader, Colin King and Louis Bouchard for a stimulating discussion on documentation this morning. :)

1 comment:

jorge said...

This manpage does not exist, it is only here to pass Debian policy.