Re: Preliminary restructuring layout (was Re: sys/ tree re-structuring proposal)

[Jeroen Ruigrok/asmodai <asmodai@xxxxxx>]

[When reading this, please keep in mind that I do (semi-)professional
documentation work as a living.]

-On [20030807 12:52], Hiten Pandya (hmp@xxxxxxxx) wrote:
>On Thu, Aug 07, 2003 at 10:39:30AM +0200, Jeroen Ruigrok/asmodai wrote:

[snip, FreeBSD's English doc repo on crater]

>	On that note, let us not import the Developer's Handbook because
>	it is a total waste of time.  Our Kernel documentation should be
>	split up into three books/parts

I completely and politely disagree with you.  Even taking aside the fact
that I instigated the Developer's Handbook in the first place, it is a
piece of documentation that is sorely needed given how ill-documented
open source projects tend to be.
Also, not everybody can afford to fork over EUR/$ 50 for a book about
programming.  Let alone multiple books about Unix development and its
kernels.
Also, most of the current documentation concerning Unix is quite dated
given recent development on the fronts of BSD and Linux.

I kindly ask you to take your mind out of the kernel for a minute and
consider the entire operation system.  An operating system does not only
appeal to kernel hackers.

Do note that I don't say that the current structure is adequate, but it
does have its needs and merits, but see below.

>		1) Kernel Reference
>		I.e. all the internal functions of the kernel described,
>		like the Linux memory management book. (linuxmm.org I
>		think)  This book will also say which locking domain (if
>		any) is affected on the particular functions.

linux-mm.org and to be frank, it has little which is truly interesting
or impressing from a documentation perspective.
The only link it has which is truly impressive is Knapka's documentation
work.  I simply am amazed at the amount of work the guy did.

>		2) Kernel Guide
>		This book will have information about *how* to use the
>		various stuff in the kernel, like making system calls,
>		kernel filters, kernel locking.

I can agree into splitting off a developer's handbook in two pieces, one
more aimed at the userland programmer and one aimed at the kernel
programmer.

I am not asking the programmers to learn arcane documentation techniques
or write interesting stories.  A simple repository of scribblings in
plain text is all I need to work from.  What I don't understand from
that or the code gets asked.
You do your thing, I'll do mine, as I like to put it.

>		3) Kernel MIB Guide
>		A reference of *all* the sysctls we have; be it minor or
>		major, it doesn't matter.

MIB documentation is certainly interesting to have, yes.

>	The DragonFly User Guide should be based on the Handbook, but we
>	will rip out things and put them back together.

The current format as used by the FreeBSD project is quite nice, but it
could use some careful replanning.

-- 
Jeroen Ruigrok van der Werven <asmodai(at)wxs.nl> / asmodai
PGP fingerprint: 2D92 980E 45FE 2C28 9DB7  9D88 97E6 839B 2EAC 625B
http://www.tendra.org/   | http://www.in-nomine.org/~asmodai/diary/
No man is good enough to govern another man without the other's consent...