TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:Re: Are UNIX manpages obsolete? From:Robert Plamondon <robert -at- PLAMONDON -dot- COM> Date:Wed, 2 Oct 1996 06:42:19 PDT
Man pages traditionally give lots of scope for choosing an appropriate
level of detail. For things like function calls, they can either
be exhaustively complete, or not. Many people who look up a C
function can't remember whether an argument is a long or a double,
and that's all they want to know. A perfectly acceptable man page
could consist only of:
* A description of the format of the command/function/whatever.
* A one-line description of each command-line element.
* A one-sentence description of what the command/function/whatever does.
* A reference to the complete description, either on-line or off-line.
Such man pages are so short that you might as well compose them by hand.
So long as you keep the cross-references sensible, you will never have
to update such a man page. (Sensible cross-references refer either
to the name of a function in an alphabetized functional reference manual,
or to a section number. Page references always blow up from revision
to revision, but section numbers can be retained, and the alphabet always
works.)
-- Robert
--
Robert Plamondon, President/Managing Editor, High-Tech Technical Writing, Inc.
36475 Norton Creek Road * Blodgett * Oregon * 97326
robert -at- plamondon -dot- com * (541) 453-5841 * Fax: (541) 453-4139
