Re: [Groff] Effective manpages, a couple of thoughts

[Clarke Echols]

I wrote manuals at HP from 1980 through 1992, and nearly five of those
years were nearly exclusively writing manpages.  The vi/ex tutorial I
wrote in 1987, later published as "The Ultimate Guide to the Vi and Ex
Text Editors" was considered the best in the industry by many for at
least the ensuing 10 years.  I'm not saying this to boast, but to
indicate the experience base I built from.  I spent 1993-1997 designing
online help for the sam(1m) system administration software implemented
in HP-UX.  Some of my work still can be found at docs.hp.com in the
HP-UX 10.0 portion of the site, including an extensive treatise on
tunable kernel parameters.  That was the result of another group of
"documenters" deciding that the kernel tuning information wasn't
important enough to include in the HP-UX System Administration manuals.
H-E-L-L-O!!!!!!  (Classic example of what happens when non-experts
write manuals for experts.)

It became very painfully apparent to me from those experiences that a
good manual/manpage writer, just like a good online-help designer and
creator, is a teacher and you can't teach what you don't thoroughly
understand.  Unfortunately, a lot of good software creators aren't
good writers in the sense of documenting in terms of
what the user needs to know from a user perspective.  It's one thing
to document how the software behaves (fine for libraries and system
calls), but an entirely different thing to document how to use the
utility/command effectively, such as the original cp(1) from AT&T
which covered cp, mv, and ln.  When I broke that into three different
manpages in 1989 there were loud, vocal objections from HP-UX "purists"
who wanted to keep the AT&T flavor (so they could diff(1) against new
AT&T source).  This was at the time that POSIX was emerging -- and
also when I kicked up the fuss that caused the POSIX committee to
ban the word "prepend" which means "to premediate" as in "he looked
at her with malice prepended" (that stirred a major uproar at HP
when I threw it in the face of a lot of other "purists").  When
I rewrote from scratch the cp(1), mv(1), and ln(1) manpages from
a user perspective as replacements for the old cp(1), I discovered
that the AT&T original page had so many undocumented holes that it
was remarkably pathetic, but the holes were not visible, even to
a trained expert, until the page was broken apart.  Thus the lesson
to me in the hazards of trying to over-compact the density of
information being presented.  So how did one page get presented for
three commands?  Simple:  The program written for cp(1) was the same
piece of code that handled mv(1) AND ln(1)!  The program looked at
the first argument in the command line to see if it was being executed
as cp, mv, or ln, then behaved accordingly.  Nifty for software space
savings, but lousy from a user perspective because the user doesn't
know (and couln't care less) that one piece of code does all three.
That is the danger in having manpages written by code developers.
They have trouble separating themselves from the code when documenting
things for users.

GOOD manpages are very difficult to write well.  It takes a seasoned
writer who has good user-perspectives but he or she must also have
a deep understanding of the internals of the operating system in
order to communicate accurately what the true behavior is in terms
that the user can translate into knowledge of how to do what needs
to be done.  Example: SYNOPSIS of cp(1) rewritten shows copy file
to file, copy files to directory, and copy directories or directory
and file trees to another directory, using three separate lines,
with a subheader above each version identifying what that version
of the syntax presentation accomplishes.  This goes over big-time
when subjected to usability testing.

I wrote a whitepaper for HP engineers to use when writing manpages
(before submitting them to me for cleanup and editing), and it worked
very well.  Unfortunately, I haven't had any contact with it since
12 years ago, and don't know where to find it if it could be found
inside of HP.  I didn't keep a copy for myself when I retired five
years ago.

[You don't know Unix editing until you can run vi non-interactively
inside a shell script, and run the file being edited in vi through
sed while you're at it.  :-)  Don't laugh.  That is how I completely
overhauled about 2500 pages of manpages from slip-shod, inconsistent
formatting into a clean man-macro-formatted set of pages with
remarkable consistency.  Once the software is written, the job
takes a couple of hours.  :-)

I took the top-of-page headings {CP(1)} and changed them to lowercase
just as in the SYNOPSIS, and also changed fonts in the text to Courier
for command/utility and syscall/library function names, and did a
whole lot of other cleanup (\f3 or \fB to .B, using .CI, .CR, etc.
for Courier macros using font position 4, etc.)  It was a big job
but the manual looked MUCH better!]

Clarke

Larry Kollar wrote:

> I'm not sure basic manpages are that easy to write... look at all the
> discussion
> this has generated. Then again, like any other kind of writing, it's
> easy to
> write but more difficult to write *well*. :-) Thus, the "effective"
> part.