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

[Hiten Pandya <hmp@xxxxxxxx>]

On Thu, Aug 07, 2003 at 07:13:23PM +0200, Jeroen Ruigrok/asmodai wrote:
> [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.

	Ok, I apologise if I sounded a little too harsh on the "waste of
	time" bit; but what I actually mean, is that we should split up
	developer's handbook into two main parts:

		1) Programming on DragonFly BSD (very less kernel stuff)
		this guide would be the stuff which the developer's
		handbook currently has minus the intricate kernel parts.

		2) Internals of DragonFly BSD (i.e., how system calls
		work, as Bill said, Interrupt handling, message passing
		and that sort of thing -- i.e. the intricate stuff.

	``Waste of time'' is the wrong phrase, but IMO, we should
	split up the Dev. Handbook first, and then import it into the
	repository -- that is what I actually meant. :-)

> 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.

	Very true.  On that note, I am having hard-time collecting money
	for Stevens Volume 2, because the book is so expenvie,
	unfortunately all the intricacies of BSD kernel net. stack is in
	that book.

	We should also document the networking internals thorougly.
	This will all take time, but it should be done sooner or later.
	
> 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.

	Yes, see my comments above about splitting Dev. Handbook into
	two parts.

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

	Yes, it does have its merits.

> 
> >		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.

	http://puggy.symonds.net/~abhi/files/mm/

	That is the one I actually mean; I thought it was linux-mm.org,
	but naturally, I was wrong. 8-)
	
> 
> >		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.

	Yes, that is what I actually mean.

> 
> 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.

	I have already asked Matt is I can create a Documentation/
	folder in the root of the CVS tree; just like there is one in
	the Linux kernel source tree.

	Once I/You/Matt create it, we can just dump things in text
	format into that folder, and then from that we can create the
	documentation.
	
> You do your thing, I'll do mine, as I like to put it.

	I am sorry I don't understand this bit (in this context).
> 
> >		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.

	Yeah.
> 
> >	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.

	Yep, maybe splitting it into a User/Admin guide, but not really
	sure on this one.

	Cheers.

	Once again, I apologise if you got the wrong meaning on ``waste
	of time'', I really didn't mean it in a bad way, but yes, it did
	sound a little harsh, sorry.

-- 
Hiten M. Pandya
hmp@xxxxxxxxxxx, hmp@xxxxxxxx
http://hmp.serverninjas.com/