From owner-freebsd-doc@FreeBSD.ORG Tue Apr 5 02:30:34 2005 Return-Path: Delivered-To: freebsd-doc@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 6CDE016A4CE for ; Tue, 5 Apr 2005 02:30:34 +0000 (GMT) Received: from rwcrmhc12.comcast.net (rwcrmhc12.comcast.net [216.148.227.85]) by mx1.FreeBSD.org (Postfix) with ESMTP id 2EFCD43D31 for ; Tue, 5 Apr 2005 02:30:34 +0000 (GMT) (envelope-from bsd@noogenesis.org) Received: from [68.84.181.60] (pcp02693964pcs.roylok01.mi.comcast.net[68.84.181.60]) by comcast.net (rwcrmhc12) with ESMTP id <2005040502303101400e7jrke>; Tue, 5 Apr 2005 02:30:31 +0000 Message-ID: <4251F848.3040200@noogenesis.org> Date: Mon, 04 Apr 2005 21:30:32 -0500 From: Derek VerLee User-Agent: Mozilla Thunderbird 1.0 (X11/20050122) X-Accept-Language: en-us, en MIME-Version: 1.0 To: freebsd-doc@freebsd.org Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit Subject: documentation and specification for freebsd internals X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.1 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 05 Apr 2005 02:30:34 -0000 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).