At Debconf5, Branden Robinson gave a talk on writing manual pages. This is a continuation of that talk, with a different slant.

Manual pages are the basic form of documentation on a Unix system. At their best, they are superb reference documentation: very quick to view and very quick to read. Once you're used to the format, finding the information you need might take mere seconds, faster even than using Google. The speed gets addictive.

According to Debian Policy, every command must have a manual page, even if it is very minimal and mostly just points the reader to a more complete manual.

Many commands are, however, missing manual pages. Partly this is because writing documentation is, for some reason, unpleasant for many programmers. When it comes to manual pages, however, a big reason is that the manual page format, troff with the "an" macros, is archaic and unusual enough that it requires adjusting to a whole new world.

There are alternatives, though. It is possible to write a manual page in DocBook/XML, specifically its refentry element, and have that converted to troff format using a simple command line tool. Writing XML is more palatable to many people these days, and also it lets you concentrate on the logical level, whereas traditional manual page writing requires using physical markup.

This talk, then, will start by introducing the DocBook refentry markup, by using a series of examples. The first example will be a minimal one, suitable for the minimum requirements for a manual page written to satisfy Debian Policy: name of command, a short description of what the program does, and a pointer to a more complete manual. Part of the first example is the process of converting the DocBook file into troff source code, with validity checking, and viewing the result.

Further examples will show how to properly document options and their meaning; other kinds of command line arguments; usage examples, with sample command lines and output; tabular data; references to other manual pages, and to web pages; and various kinds of lists, numbered or otherwise.

The second part of the talk will concentrate not on the mechanics of producing an input file for the man command, but on writing a really good manual page.

I will discuss stylistic, linguistic, and usability issues with manual pages: the importance of being terse without being incomprehensible; using short sentences and paragraphs for online reading comprehension; various idioms specific to manual pages; mandatory and optional parts of the structure of a manual page; dividing things into several manual pages; and more.

This part will be done as a series of opposite examples: an example of a bad way of doing something, and then showing the good way of achieving the same thing.

I propose this as a talk, 45 minutes long, but if the organizers prefer, it could be restructured into a 90 minute workshop, where the participants would write or update their own manual pages after a shortened version of the above talk, and get feedback and suggestions on what they have done.