Skip site navigation (1)Skip section navigation (2)
Date:      Wed, 18 Oct 2000 16:27:50 +0100
From:      Steve Roome <steve@sse0691.bri.hp.com>
To:        Rasmus Kaj <kaj@raditex.se>
Cc:        Jordan Hubbard <jkh@winston.osd.bsdi.com>, peter@sysadmin-inc.com, "'Jason C. Wells'" <jcwells@nwlink.com>, freebsd-doc@FreeBSD.ORG
Subject:   Re: How To's [about to get flamed]
Message-ID:  <20001018162750.H25899@moose.bri.hp.com>
In-Reply-To: <844s2adxo1.fsf@frodo.sickla.raditex.se>; from kaj@raditex.se on Wed, Oct 18, 2000 at 04:35:58PM %2B0200
References:  <peter@sysadmin-inc.com> <64326.971803991@winston.osd.bsdi.com> <20001018144654.C25899@moose.bri.hp.com> <844s2adxo1.fsf@frodo.sickla.raditex.se>

next in thread | previous in thread | raw e-mail | index | archive | help
On Wed, Oct 18, 2000 at 04:35:58PM +0200, Rasmus Kaj wrote:
> >>>>> "SR" == Steve Roome <steve@sse0691.bri.hp.com> writes:
> 
>  SR> This is long, and not intended to offend anyone.
>   [ It is also about how FreeBSD might have _good_ docs, but not
>     enough docs, while Linux have much more docs, even if the quality
>     varies (just to summarize, no flame intended anywhere) ]
> 
>  SR> This is because it's so damn difficult to contribute anything for most
>  SR> of us. Maybe not for you, but that's different!
> 
> How about this for a suggestion:
> 
> We keep working on the documentation as currently, valuing quality
> over quantity.  But at the same time, we sound a "call for papers" (to
> use your words), and compile a list of _links_ to such documents on
> the web. We mention (link to) this list in the handbook, but the list
> goes up at the web, not the handbook.

I think this is a brilliant idea, but that the docs themselves ought
to go to a sort of "scratch" area all on one machine if possible.

How about docs.freebsd.org if there's available bandwidth/space and
people are okay with it ?

We all throw things at it, and people can rewrite and submit new
versions and improvements over the web. (I bet there's some really
simple software to do this already - I'll have a look if there's no
proposers!)

All the hardcore doc folks who are willing and able can convert these
to sgml (and make improvements at the same time perhaps) and we
suddenly have a much large base of folks working on docs and much
more material for people to work with putting stuff into the handbook.

I agree with you, it has to be easy though!

>  SR> We don't have a bind 8 howto. (because we don't do howto's as someone
>  SR> rather snobbishly stated earlier in this thread!) 
> 
> In case there was no documentation for bind, that would indeed be a
> bogus answer.  If you don't find the existing documentation just
> because it's not named how-to it is a good answer.  Reality seems to be
> somewhere in between, I don't find any documentation on bind in the
> handbook or on the FreeBSD web page, but I do find /usr/share/doc/bind

Yeah, the misc stuff is really outdated though, and although the html
docs are very thorough, there doesn't appear to much in the way of
"getting it done", just a "the whole deal" type documentation, which
is really frustrating when you have a broken system that needs a fix
right now! [joke : one shouldn't mess with Unix until one understands it
completely - bit of a barrier to learning there! ]

> This case seems to be "why should FreeBSD write own documentation for
> contrib stuff that has its own docs".

A lot of stuff on HP-UX has it's own docs (I'm not saying anything
about quality!), especially the taken from BSD stuff. Even meagre
amount of contrib stuff, it makes the users/admins feel happier that
they have an HP-UX system, rather than a generic kernel with some
downloaded apps stuck on it! Not that I'm saying that's what HP-UX is
of course, nor FreeBSD, nor Linux - although linux is just that!

But strangely Linux is seen by many as an "OS" (not just a kernel) and
I think it's because people treat it as one entity, docs as well.

	Steve

P.S. sorry for rambling again.


To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message




Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20001018162750.H25899>