man pages and handbooks

[Duane Whitty]

I've been spending a lot of time recently reading how SMP works, kernel
threads, SA/KSE, callouts, the differences between SCHED_4BSD and SCHED_ULE,
locking, caches, etc.  I've still got a lot to learn and a lot to actually
start trying to apply in code.

I've often thought this might be easier if some of the great material
available in the man pages was perhaps streamlined into the evolving
FreeBSD Architecture Handbook.  This is just my opinion of course and
those of you with more experience than me may have good reasons for
not doing so.

Barring any objections from the community in general and the DOC
project comitters in particular I would like to volunteer to
start adding some material from the man pages into the
FreeBSD Architecture Handbook.  My first targets would be integrating
the material on mutex(9), mtx_*(9), pthread_*(9), lock*(9), atomic_*(9),
sched_4bsd(4), and sched_ule(4) into the material already present in the
handbook.  I would also like to try my hand at creating diagrams to illustrate
the data structures used in our kernel code.  Obviously as I learn more
I will probably find more material which would be interesting to have
integrated as well.

Because of the time an ongoing project like this would take,
would I be correct that doing this for the 7.X branch would
be the most practical course of action and then MFCing where
applicable and time allowing?  I hope this raises some interest
because I am sure that during the review process many misconceptions on
my part about how things work would be brought to light and maybe help
some additional future developers as well.  

Best Regards,

Duane Whitty