Re: Linux docs (was:Re: [tlug] Re: IPv6)

[Scott Robbins <scottro@example.com>]

On Sun, Nov 18, 2007 at 03:48:32PM +0900, Stephen J. Turnbull wrote:
> Scott Robbins writes:
> 
> kernel you have than to which libc you have) are definitely better
> documented than Linux's (although I'm more familiar with NetBSD than
> FreeBSD).  But they've been at it for longer, and they have a much
> smaller, more coherent code base with fewer features to deal with.

So, you feel my reasoning, that it was because their target audience was
too buzzed to understand is wrong.  :-(.   Oh well, it makes a better
story.

> 
> Don't hold me responsible for GNOME.  I hate GNOME, I think it sucks
> in all ways.  In any case, since there's no FreeBSDish replacement for
> GNOME per se, it's not really fair to bring it up in a comparison
> between Linux and BSD practices.
> 

Heh, I wouldn't hold anyone I respect responsible for it.  There was a
rant last night on Fedora forums about the Gnome Docs.  And a post on
FreeBSD forums today which I wanted to quote, just for fun
+++++++++++++++++++++++++++++++++++

I've stumbled on OpenBSD, and intrigued by the quality of technical
documentation provided (where, with a few exceptions, Linux
distributions IMHO
lack), now I'd like to adopt OpenBSD as server OS in a production
environment.
++++++++++++++++++++++++++++++++++++++++++++++



>  > a friend of mine says, have sparse docs for the user, good docs for the
>  > developers, and nothing in between.
> 
> I don't see that GNOME docs are good for developers, personally.
> They're mostly just automatically reformatted header files.  "Use the
> Source, Luke" with gewgaws on.

He is not a developer either, he was saying what a developer had told
him.  What you say though, doesn't surprise me (nor will it surprise
him.)

> 
> 
> Oh, that's easy to explain.  "He whose program pulls in the most
> gratuitous dependencies wins" is the way they score at GNOME.  It's
> worse than Emacs LISP, I swear it is.

Ok Stephen, had I been drinking something as I read that, you would have
owed me a monitor.  Had the cat been asleep on my lap, you would have
owed me--well, never mind.  

>  > /etc/rc.conf.  Each one has a man page that gives a pretty good idea of
>  > why you should or shouldn't have it.  I wish that Fedora had that, and
>  > feel that its lack is a Bad Thing(TM). 
> 
> It's a bad thing in servers, for sure.  But what you'll discover is
> that the FreeBSD guys don't document the plethora of user "services"
> provided by GNUMB and KiDdiE any more than the Linux guys do; they
> just port the code.  Cf. http://www.jwz.org/doc/cadt.html.

I agree--see my comments above on avahi-daemon.  The FreeBSD folks (as
they do with most 3rd party apps) use what's provided, which is by
gnome. 

I think a large part of it is attitude.  Many coders, I assume, want to
code, not document.  The OpenBSD people, however, are proud of their
documentation, and Theo comments that code is never included without
proper docs.  Regardless of what one thinks of Theo, it seems the the
whole environment, peer pressure, etc., rewards those who document. 

The FreeBSD jail man page is another good example.  Written by one of
the nicest of the FreeBSD folks, Robert Watson (incredibly patient with
newcomers on the mailing lists) it seems to be written by someone who
really wants you to understand how to use it.  

Many third party programs are like that too.  The fluxbox man page, for
example, seems to be written by someone who is probably part of the
team, proud of the creation and WANTS people to understand how to use
it. There's a certain enthusiasm in the man page.  The same can be said,
for example, of pure-ftpd.  


-- 
Scott Robbins
PGP keyID EB3467D6
( 1B48 077D 66F6 9DB0 FDC2 A409 FA54 EB34 67D6 )
gpg --keyserver pgp.mit.edu --recv-keys EB3467D6

Harmony: So Slayer. At least we meet.
Buffy: We've met Harmony, you half-wit.