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

[Meg McRoberts]

--- Jon Snader <address@hidden> wrote:

> I reluctantly must agree with this.  As annoying as long man
> pages are, they're preferable to omitting vital information or,
> worse yet, the odious Perl practice of making every single
> function a separate man page.
> 
> We may be overworking this issue.  The point of Larry's paper is
> to lay out some guidelines for making man pages useful, not to
> serve as draft legislation.  If we all keep our man pages as
> short as possible while covering the required material, we will,
> in general, limit most man pages to a MANagable 8-) length.  Some
> cases, such as bash, just have to be exceptions.
> 
> As others have said, the info system is a non-starter for me.

I think a distillation of this discussion would be a very interesting
addition to this paper.  It's taken the rest of us a long time and a
lot of man pages to understand the issues, and this information could
be very helpful to people who are just starting to write man pages.

I'm actually facing the need for such a little paper and thought about
starting one.  The company where I work has been a Windows shop with a
few Linux products.  The Linux work is growing and *someone* started
doing man pages for the Linux products.  Other writers want to learn
how to do man pages.  To do this, they need to learn the macro set and
all but they also need to learn how to structure the information for a
man page.  I think we all agree that the "ideal" man page is quite short,
and thinking of brevity is a good idea even when the subject matter requires
that the man page be long.

meg


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