[Debconf-team] Still can't log in
The conference management system a) still claims that my username or
password are wrong (they're not); and b) refuses to give me a new
password. The reason I claim that my username and password are correct
is that a1) I enter them into Revelation and the copy/paste them into
the browser and a2) my browser remembered the same ones from my first
talk proposal submission and now they no longer worked.
Since I think it would be silly to create a new account for myself, I'm
mailing my second talk proposal so that it arrives by the deadline. If
my account is fixed, I'd be happy to paste it into the system myself.
Incidentally, the pages work pretty badly on a browser that isn't very
wide. My browser is about 700 or 800 pixels wide, and the side bars take
up most of the space (but still manage to not be fully visible), making
the main text area very difficult to read. It would be good to fix this.
--
Fundamental truth #3: Communication is difficult.
WTFM part 2: Avoiding Tears and Loss Of Hair
============================================
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.
Reply to: