documentation and specification for freebsd internals

[Derek VerLee]

I try not to waltz into a massive project and start pointing out things 
that could be changed before I even take my shoes off, please see this 
more as a result of my respect and willingness to learn and be involved 
then as a presumption of knowing better; I obviously don't. 

Having said that, I think there is a lot to be gained by improving the 
documentation (including more attention to specifications (pre and 
post-facto) of  the freebsd source.  It is clean and easy to follow, and 
it contains at least as much probably more, documentation then average, 
but not nearly enough.  More specification means more contributers, 
quicker contributions, improved ability to audit other's code, fewer 
bugs, and easier smoother redesigns.

Frankly I don't know of any programmer who likes to document their code 
as much as they like writing it, and most (myself included most of the 
time) just like to add a comment here or there that begrudgingly gives a 
nod to the concept of documentation and then move on to the more 
interesting part about seeing results.  This behavior isn't really going 
to change, so I'm not going to suggest that it does.

((btw all this could be made mute if there is some large resource for 
this sort of information that I haven't come across.))

The idea I have, though admittedly it is somewhat abstract at the 
moment, is for putting a formal system in place to make documenting the 
source easier for both the developers who are the primary contributers 
to a specific piece of code as well as other interested in enhancing the 
specification or documentation.  "All right", your saying, "the guy just 
basically described what is already in place".  I'm thinking about going 
beyond what is already in place, and doing so for the source code 
specifically, not as much the userland documentation which, as far as I 
can see, are doing just fine as things are.  I'm thinking about a system 
that goes beyond incline code comments, allowing things like embedded 
graphs, diagrams, images, etc, hyperlinking, and so forth, and allowing 
for more verbose code documentation without fear of detracting from the 
readability of the functional code (by setting it awash with a flood of 
incline commentation).  It'd also have the advantage of being a seperate 
project/package then the source itself, so not everyone who wishes to 
build world need bother with downloading it.

Actions speak louder then words, but, as I'm going to be somewhat slow 
implementing a prototype, and as a newb freebsd hacker, i'm likely to 
get it all wrong, miss the point entirely, or otherwise waist my time if 
I don't at least get some feedback.

What I'm thinking is:

*Documents in the source documentation database are associated with 
either files or directories in /usr/src.

*Document format supports embedded objects, hyper-links to other 
documentation objects, url's, emails, man pages, code source, or 
whatever else you can think that would be useful

*there be an agreed upon set of formal specification languages and 
documentation-related tools and utilities (as there is already, but 
extended for this purpose), as well as a repository of freebsd specific 
extensions to those languages and tools. Of course, one is free to 
document in whatever way they think conveys the information best, but 
there should be some commonalities available.

*people could add forum style comments to any given document, probably 
through a web interface.  This way people could easily raise issues, 
make requests, point out flaws, or most importantly, record little 
tidbits of wisdom they have gained about the subject through 
experience.  One "forum" associated with each documentation object.

_derek

(This message is paraphrased from an even longer post I made on -hackers 
a few days ago).