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

[Steve Izma]

I generally agree with Meg's perspective that the concise,
general material be up front and more detail in subsequent
sections. However, my idea of a short man page for, e.g., groff
is:

groff --help

I don't generally consult a man page unless I need the details of
an option.

I think we should keep in mind the Unix philosophy in this
matter: when programs adhere to it fairly clearly, then short man
pages are all that's necessary. In other words, if a program does
one thing and does it well, a description of it can be short and
easily grasped.

The problem is that some utilities we use are not really mere
Unix tools -- they're systems, and groff is a good example of
this, along with various shells, vi, and various programming
languages. I don't even want to mention emacs, which is in a
category of its own. I think these systems are special cases and
their needs should be kept isolated from the needs of typical
Unix tools. Many non-command-line progs are systems as well
(e.g., the GIMP, OpenOffice) so I think documentation for them
requires a different approach. Since you can't really use these
"systems" effectively without spending a lot of time learning and
experimenting, perhaps their man pages should describe concisely
their purpose and general capabilities, and then point to the
tutorials and reference manuals.

        -- Steve

-- 
Steve Izma
    Computing Systems Administrator       (519) 884-0710 ext. 6125
    Wilfrid Laurier University Press      FAX: (519) 725-1399
    Waterloo, Ont., Canada N2L 3C5        address@hidden