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

[Meg McRoberts]

I've been discussing some of this offline with Ted but thought
I would chime in here.

I "grew up" with the idea that the man pages should be small, concise,
reference documents and the more expansive information should be in
some other format.  In some "purist" part of my brain, I still believe
this -- non-manpages can include nice graphics, equations, and generally
be more pleasing to look at.

However, I've learned that non-manpages can be harder to locate and that
many technical people are not as book-oriented as I am.  I've noticed
that, for a lot of people, "the documentation" is the same thing as "the
manpages" -- everything else is fluff and it's hard to get anyone to look
at it.

So my thinking has evolved and now I am inclined to think that the man page
should be the complete repository of information about a command/function/
file/device.  I don't mean that it should be a tutorial or anything, just
that all the basic information should be there.  These days, project resources
are often tight and you can't get everything done, but if the man pages are
complete and accurate, people will survive.

However, we still need to avoid some of these verbose, stream-of-consciousness
man pages.  I've had many discussions with people who want the information that
interests them to be at the very beginning of the page, which makes sense.  
Alas,
everything on the page could qualify for that...  Still, my recommendation for
the basic structure is:

   Synopsis/Syntax
   Description (very brief -- one to two sentences)
   Options/Arguments/Structure Members/whatver
       use a hanging list and define each option/arg/etc precisely
   Usage (this is where you can digress into longer discussions about how the
       command/function/structure/whatever is used, give advice, and so forth
   Differences between versions (very important to capture when a feature is
       added, usually by version/release number) and, if an option or argument
       is retired, it's nice to retain the info for a release or two.  So I just
       put it here)
   Examples
   See also/Reference
       I've been convinced that this should be the last thing so that people can
       easily skip to it.  Once in a while, the Examples material is quite long
       and I'm a little bothered by burying the references but I think it does
       make sense.

So I don't agree that man pages should be limited to a couple of pages but
they should be well-structured and concise, especially at the beginning.

meg

--- MJ Ray <address@hidden> wrote:
> On 2004-05-03 12:13:31 +0100 (Ted Harding) 
> <address@hidden> wrote:
> 
> > Maybe this is a "generation" thing. People who dug their way into
> > UNIX in the old days developed a facility for mentally linking the
> > cross-references implicit in the old-style man pages, [...]
> 
> Probably not a "generation" thing. I've used and written both. I'm 
> quite emacs-friendly, so info navigation causes me no trouble. Despite 
> that, I prefer to have man pages for executables. I think info is a 
> better format for electronic books, although I'm not sure it has much 
> advantage over well-produced xhtml-based ones any more.
> 
> Yes to one page per executable. It lets you see at a glance just why 
> zsh and bash are way too complicated ;-) perlfaq almost certainly 
> shouldn't be man pages...
> 
> -- 
> MJR/slef
> My Opinion Only and possibly not of any group I know.
> http://mjr.towers.org.uk/
> http://www.ttllp.co.uk/ for creative copyleft computing
> _______________________________________________
> Groff maillist  -  address@hidden
> http://ffii.org/mailman/listinfo/groff



        
                
__________________________________
Do you Yahoo!?
Win a $20,000 Career Makeover at Yahoo! HotJobs  
http://hotjobs.sweepstakes.yahoo.com/careermakeover