Date: Thu, 23 Dec 1999 21:26:45 -0500 (EST) From: Colin <cwass99@home.com> To: Mike s <god@yahoo.com> Cc: stable@FreeBSD.ORG Subject: Re: bugs in the handbook. (FreeBSD Portal) Message-ID: <XFMail.19991223212645.cwass99@home.com> In-Reply-To: <19991223184115.4862.qmail@web504.mail.yahoo.com>
next in thread | previous in thread | raw e-mail | index | archive | help
I don't think we don't care about the documentation, that strikes me as
something of an oversimplification. There are 2 distinct problems here:
1) The peole who know enough about the system to document it properly
generally don't have the time (or inclination...gotta love those programmers ;))
to spend on documentation. They're too busy fixing the problems that turn up
regularly or adding enhancements (which is where most of the problems start ;)).
2) The peole who are most willing to spend time on the documentation don't have
the specific knowledge to do it. They are the one's who would like to be
reading the docs.
Yes, I know it's inappropriate to generalize that much, but I think you
get the idea. There is, of course, quite a lot of good documentation out there
already, most of it accessible on-line. There is a definite need for ongoing
improvement and upgrading, but I don't think that surprises anyone.
There's an interesting article at
http://www.firstmonday.org/issues/issue4_12/bezroukov/index.html that talks
about the problems of documentation in the Open Software world. Actually, it
is just a really good second look at the "Cathedral and Bazaar" with a section
on documentation. The upshot is that we cannot accept the code as sufficient
documentation for something this complex and there is a definite need for a
complete higher level view.
To meet that need there are several really good resources including "The
Design and Implementation of the 4.4BSD Operating System", and "The Complete
FreeBSD". There are,as well, several really good on-line reources, not least
of which is the FreeBSD HowTo. I know there are more (not including the general
Unix books) but titles escape me right now.
Add the books to the FreeBSD specific web sites we already have, and i'm
not sure the problem is lacking docs, rather slightly out of date docs due to an
ambitious schedule of updates and releases.
To start adding additional "Home of the Docs" sites would, IMHO, actually
add to the confusion and difficulties. We would be much better served by
people submitting pr's (where appropriate ;)) or suggestions that could be
integrated into the existing docs. I'm not convinced (having wandered aimlessly
down that road) the Linux style of documentation (1000's of sites, no real
organization ;)) is the best bet here.
On 23-Dec-1999 Mike s wrote:
> Well, as i can see not many people care about the
> documentation, or at least providing FreeBSD users
> .......etc.......................
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-stable" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?XFMail.19991223212645.cwass99>