Date: Thu, 7 Sep 2000 20:37:10 +0100 From: Nik Clayton <nik@freebsd.org> To: Jordan Hubbard <jkh@winston.osd.bsdi.com> Cc: mjacob@feral.com, Nik Clayton <nik@FreeBSD.org>, Warner Losh <imp@village.org>, "David E. O'Brien" <obrien@FreeBSD.org>, cvs-committers@FreeBSD.org, cvs-all@FreeBSD.org Subject: Re: cvs commit: src/sys/boot/common boot.c module.c src/sys/boot/forth loader.conf src/sys/conf Makefile.alpha Makefile.i386 Makefile.pc98 kmod.mk src/share/mk bsd.own.mk Message-ID: <20000907203710.B20005@canyon.nothing-going-on.org> In-Reply-To: <24866.968353259@winston.osd.bsdi.com>; from jkh@winston.osd.bsdi.com on Thu, Sep 07, 2000 at 12:00:59PM -0700 References: <mjacob@feral.com> <24866.968353259@winston.osd.bsdi.com>
next in thread | previous in thread | raw e-mail | index | archive | help
On Thu, Sep 07, 2000 at 12:00:59PM -0700, Jordan Hubbard wrote: > I would be the first to agree that communications and documentation > could be a lot better in the FreeBSD project. What's never been made > clear to me or anyone else, however, is just how to magically make it > all better. Lead by example? > Getting docs or timely status reports out of PAID > engineers is already so much of a chore Search for more professional engineers. I've done my fair share of software development, and it was a matter of pride that the people I was working with were able to understand why things were done the way they were, because there was documentation they could read that explained things. Look at the Doc. Project as an example. The switch to DocBook and the different organisational work underlying that change was huge, which is why I started working on doc/en*/books/fdp-primer to accompany it, to make sure that I wasn't the only person that understood the changes, and the reasons for them. I also make sure that there's lot of opportunity for 'architectural' discussion on the -doc list. > that it remains a mystery to > me just how we're supposed to motivate unpaid volunteers to do a > better job. By requiring 'major' commits to have accompanying documentation before they're allowed in to the tree. c.f., DEVFS -- I'm not beating on Poul here, but, IIRC, he said that documentation would have to wait for five or six weeks after the commit until he had time. Well, we've waited long enough for DEVFS, we can wait five or six weeks more until there's accompanying documentation. This would also allow interested people to read the code alongside architecture notes, opening up the review process to more people. s/DEVFS/project of your choice/ in the above, rinse, repeat. We shouldn't be accepting major architectural changes without accompanying documentation, and the core team (and principal architect, a position which I understand is now unfilled) should enforce that. N -- Internet connection, $19.95 a month. Computer, $799.95. Modem, $149.95. Telephone line, $24.95 a month. Software, free. USENET transmission, hundreds if not thousands of dollars. Thinking before posting, priceless. Somethings in life you can't buy. For everything else, there's MasterCard. -- Graham Reed, in the Scary Devil Monastery To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe cvs-all" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20000907203710.B20005>