Re: [Groff] Draft paper: "Writing Effective Manual Pages"

[Larry Kollar]

Some general comments... I started with a lengthy response to Jorgen,
but couldn't keep up with the other stuff rolling in.

Despite the pings, I think this is a productive discussion. Heck, if I was
going for universal agreement, I'd have written a paper like, "Why You
Shouldn't Use Texinfo." :-D

One thing that everyone who has responded so far has said, with
varying degrees of emphasis, is that my suggestion for a two-page
limit is too tight. Most seem to agree that the bash manpage is too
big, so we at least have a consensus between 3 and 57 pages.
I still want to lean very close to the low end of that range, though.
Let me provide a little background for my thoughts.


First, there's the concept of short-term, or "working" memory, as
described at 
http://www.psych.ualberta.ca/~mike/Pearl_Street/Dictionary/contents/
S/short_term_memory.html

        ... short-term memory can contain at any one time seven, plus
        or minus two, "chunks" of informaton.  Second, items remain
        in short-term memory around twenty seconds.

This is important to modern technical writers, as reading for
information tends to use short-term memory. In general, that
means lists, sections, and other divisions need to fall in that
7 +/- 2 limit. The major headings of a manpage are usually
in that range.

However, the 20-second time limit means that unless you're
familiar with the layout of a long manpage, you're going to get
lost in a hurry. As an experiment, I started "man bash" in an
xterm window and started skimming the headings. In 20 seconds,
I got to "Shell Variables" -- the top of page 8 if you created a
printed version. So perhaps 7 printed pages is a reasonable
upper bound, and I wouldn't be a hypocrite because my rewrite
of groff_ms.7 is seven pages + 1 paragraph long. :-)

(I'm using printed pages as a yardstick since everyone sets
their own length for shell windows.)


The other thought is that so much of our console software has
outgrown the mental limits of manpages that I describe above.
The yardstick for manpages is "short and complete" because
in the Elder Days manpages *could* be both short and complete.
For example, the longest manpage in section 1 for Unix 3rd
Edition was the complete reference for ed(1) and it runs about
5 printed pages (I'm guessing, since the source appears to have
been partially compiled down to *roff requests but using back-
spaces to generate underline/emphasis). The sh(1) manpage
was a little shorter, maybe 4 pages. The others were significantly
smaller; certainly none of them approach that 7-page limit.

http://minnie.tuhs.org/UnixTree/V3/usr/man/man1/ed.1.html

It's a little harder these days, at least in some cases. Today's
bash (v2.05) is nearly 15x larger than its ancestor. Even the
ed(1) manpage on my iBook is about 8 pages. Granted, a lot
of other manpages aren't nearly that big, but they're not the
ones I'm worried about at the moment.


But none of that makes manpages irrelevant. To put it bluntly,
there is no other format out there that is both widespread and
allows both console viewing and printing from the same file.
Despite attempted marginalization by the FSF and others,
people still type "man foo" first thing. Speaking as a technical
writer, this is good; it means that I know what to provide.

Thus, the answer is certainly not the Netpbm abomination of
"Netpbm documentation is kept in HTML format. Please refer
to [an external website]." Oh, you're not online? Rats. HTML
has a lot of nice qualities, not the least of which is hyperlinking,
and well-formed HTML can be rewritten in a variety of ways
for storing, indexing, or printing. Meg was telling me how SCO
(back when SCO was a Unix company instead of a lawsuit
factory) modified their version of "man" to display an HTML-
formatted manpage using Lynx. Clever, but not universal.
Besides, groff's HTML driver does a fair job of formatting
manpages, and continues to improve.

Texinfo isn't the answer either. Certainly, it has several
desirable qualities, such as cross-referencing and indexing
capabilities. But I've noted my disdain, shared by many
here, for the console info viewer before. More relevantly,
Texinfo hasn't really caught on outside the FSF. Finally,
some of the converters don't work too well if you don't stick
with canonical Texinfo (try running "texi2html groff.texinfo"
some time to see what I mean).

Nor is DocBook. I hate disagreeing with ESR, but many
documentation people and XML experts, even Norm Walsh
himself, think DocBook has become too unwieldy.
http://norman.walsh.name/2003/05/21/docbook


So despite its age, despite software growing beyond the
comfort zone where its documentation *can* be both short
and complete, despite attempts to supplant it, the venerable
manpage remains both necessary and useful. Rather than
evangelizing, as Alejandro suggested, my motive was to
illuminate the limitations of the format and (I hope) illustrate
some best practices for making the most of what it offers.
(And "gracias" to Alejandro for the offer to translate!)

Perhaps the goal should become "short, and where possible,
complete." Quick references, also known as cheat sheets, only
become necessary once the full documentation gets too big
to navigate quickly. Does anyone disagree we're at that point?


Off to spend a little of this energy on the paper itself; keep
the comments coming!

--
Larry Kollar     k  o  l  l  a  r  @  a  l  l  t  e  l  .  n  e  t
Unix Text Processing: "UTP Revival"
http://home.alltel.net/kollar/utp/