documentation

[Karsten M. Self]

on Mon, Aug 27, 2001 at 06:38:42PM -0700, David Johnson (david at usermode.org) wrote:
> On Monday 27 August 2001 12:41 pm, Matthew C. Weigel wrote:
> 
> > Not as a primary topic of discussion, no.  Unaffiliated
> > documentation suffers from bitrot at a much higher rate than
> > affiliated documentation (and how often do you find out-of-date man
> > pages in Linux?).
> 
> A bit off topic, but I find out-of-date man pages in Linux every day!
> However, I have rarely if ever found an out-of-date man page in
> FreeBSD. The reason is simple. GNU discourages man pages.

What's that old canard about answers that are simple, appealing, and
wrong?

There are any number of reasons that GNU/Linux manpages have tended to
lack.  One is indeed the emphasis GNU/FSF have placed on info
pages...though these are widely condemed elsewhere.  Another is that
programmers typically don't like writing docs.  A third is that the BSDs
(I run an oBSD firewall, and am familiar with its online docs) have made
writing and updating manpages a priority.  As much GNU/Linux development
happens outside the immediate auspices of the FSF, the old "GNU
discourages man" gripe fails.

The biggest difference is policy.  In the case of the BSDs, there's a
policy (stated or otherwise) for keeping manpages up to date.  Few
GNU/Linux distros are policy driven.  A notable exception is Debian,
which is driven by Debian Policy, and answers to central goals and
directives rather than merely aggregating packages [1].  As an instance
of policy/implementation mismatch, I recently found that RH 6.0
neglected to include /usr/share/man on its manpath, and found
discussions suggesting that /usr/share/man was deprecated.  Despite
this, the rpm manpage (that's the Red Hat Package Manager, you'll
recall...) was in /usr/share/man.  More recent RH versions appear to
have adopted /usr/share/man over /usr/man.


--------------------
Notes:

1.  In the ongoing debate over best distributions and packaging formats,
    Debian Policy is often overlooked.  I feel that Debian policy is
    *the* salient difference between it and other GNU/Linux
    distributions.  Policy makes Debian rather more like the *BSDs than
    other distros.  It also introduces a new level of quality control
    (and much room for debate):  policy conformance.  A package can
    perform perfectly well on all technical points, but still fail to be
    policy conformant.

-- 
Karsten M. Self <kmself at ix.netcom.com>          http://kmself.home.netcom.com/
 What part of "Gestalt" don't you understand?             There is no K5 cabal
  http://gestalt-system.sourceforge.net/               http://www.kuro5hin.org
   Free Dmitry! Boycott Adobe! Repeal the DMCA!    http://www.freesklyarov.org
Geek for Hire                        http://kmself.home.netcom.com/resume.html
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 232 bytes
Desc: not available
URL: <http://lists.opensource.org/pipermail/license-discuss_lists.opensource.org/attachments/20010827/0b82b64c/attachment.sig>