Date: Wed, 13 Sep 2006 12:40:23 +0200 From: Joel Dahl <joel@FreeBSD.org> To: Paul Wilson <paulalexwilson@gmail.com> Cc: Freebsd-doc@freebsd.org Subject: Re: man pages and handbooks Message-ID: <1158144023.670.36.camel@localhost> In-Reply-To: <3c3d11cf0609130258s5ebf8274q18acf31a83b403a7@mail.gmail.com> References: <3c3d11cf0609130258s5ebf8274q18acf31a83b403a7@mail.gmail.com>
next in thread | previous in thread | raw e-mail | index | archive | help
On Wed, 2006-09-13 at 10:58 +0100, Paul Wilson wrote: > On 12/09/06, Duane Whitty <duane@dwlabs.ca> wrote: > > > > Paul Wilson wrote: > > > Duane, > > > > > > I was interested to read of your proposal to update the FreeBSD > > > Architecture Handbook on the documentation mailing list. It seems that > > > we've been experiencing similar problems of late; I too have been trying > > > my best to acquaint myself with SMPng, the different locks, atomic > > > operations etc, but have found the lack of native FreeBSD locking > > > documentation and advice to be a hinderence. Of your suggestions I > > > particularly liked the idea creating diagrams for illustration and > > > believe that they would be well applied for communicating lock > > > interactions. > > > > > > If you are open to assistance with your project then I would be more > > > than happy to help. > > > > > > Paul Wilson > > > > Hi, > > > > Of course help is always welcome. What we should do, IMHO, > > is use the doc mailing list for our communications. That > > way if others also want to join in they can. As for the > > mechanics of collaboration I'm not sure what the best > > approach is just yet. I guess one thing we could do is post > > patches to a website or either of us could setup a > > repository for the project. The problem then becomes > > keeping it synched with the FreeBSD doc repository. > > > > I suggest we bring this to the list. Perhaps there would be > > an interested doc committer who could fast-tract commits > > into HEAD if they were technically accurate or perhaps a > > Perforce project could be started; I don't know. I guess > > setting-up our own repository would take care of > > communication. As most of the new development is going into > > the kernel infrastructure and manpages we probably don't > > need to worry too much in staying synched with the official > > version of the FreeBSD Architecture Handbook. > > > > And just as a note I want to reaffirm that, for me, this is > > a longterm project requiring a significant amount of > > research. I personally don't anticipate generating huge > > volumes of material in any one week. > > > > I think as well we will need a great deal of help from > > various kernel systems developers if we are to be sure our > > information is accurate. > > > > If you wouldn't mind, perhaps you could forward this to the > > freebsd-doc@freebsd.org mailing list with your original > > message intact so that we can receive some feedback from the > > community on how to best go about collaborating on this project. > > > > One of the most important issues for me is that everyone and > > anyone who desires to participate be able to do so. The > > real strength of the FreeBSD project is the FreeBSD > > community. Without that community no amount of individual > > technical achievement will be able to keep the FreeBSD > > project the vibrant entity it is today. I'm sure we can come up with a solution if you (Paul and Duane) really are interested in doing this work. Perforce could be a good solution, especially since our kernel developers actively read p4 diffs and could comment on your progress. Also, submitting your work back to FreeBSD and syncing with the doc repository should be easy if you use p4. The problem with our perforce repository is that it's quite hidden... The Architecture handbook, the Developers handbook, manual pages and the general lack of documentation have been the target for many complaints during the years. It is quite hard to get familiar with our kernel infrastructure, and it's not always obvious who to ask when new questions arise. The general rule though is that the arch@ and hackers@ mailing lists should be your first stop when you need to get in touch with someone that has the right kernel knowledge. The project will loose future developers if the lack of documentation is a too big obstacle, and this will surely hurt the project in the end, but I'm sure we can arrange something or develop a solution if you really are interested in fixing this major PITA. -- Joel
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?1158144023.670.36.camel>