From owner-cvs-all Tue Jun 22 16:24:18 1999 Delivered-To: cvs-all@freebsd.org Received: from allegro.lemis.com (allegro.lemis.com [192.109.197.134]) by hub.freebsd.org (Postfix) with ESMTP id AB3F114CD1; Tue, 22 Jun 1999 16:23:21 -0700 (PDT) (envelope-from grog@freebie.lemis.com) Received: from freebie.lemis.com (freebie.lemis.com [192.109.197.137]) by allegro.lemis.com (8.9.1/8.9.0) with ESMTP id IAA17680; Wed, 23 Jun 1999 08:53:12 +0930 (CST) Received: (from grog@localhost) by freebie.lemis.com (8.9.3/8.9.0) id IAA04035; Wed, 23 Jun 1999 08:53:15 +0930 (CST) Date: Wed, 23 Jun 1999 08:53:15 +0930 From: Greg Lehey To: Doug Rabson Cc: Hellmuth Michaelis , nick.hibma@jrc.it, mike@smith.net.au, peter@FreeBSD.ORG, cvs-all@FreeBSD.ORG, hackers@FreeBSD.ORG Subject: Re: All this and documentation too? (was: cvs commit: src/sys/isa sio.c) Message-ID: <19990623085315.S76907@freebie.lemis.com> References: Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 0.95.4i In-Reply-To: ; from Doug Rabson on Tue, Jun 22, 1999 at 07:19:47PM +0100 WWW-Home-Page: http://www.lemis.com/~grog X-PGP-Fingerprint: 6B 7B C3 8C 61 CD 54 AF 13 24 52 F8 6D A4 95 EF Organization: LEMIS, PO Box 460, Echunga SA 5153, Australia Phone: +61-8-8388-8286 Fax: +61-8-8388-8725 Mobile: +61-41-739-7062 Sender: owner-cvs-all@FreeBSD.ORG Precedence: bulk On Tuesday, 22 June 1999 at 19:19:47 +0100, Doug Rabson wrote: > On Tue, 22 Jun 1999, Hellmuth Michaelis wrote: > >>> From the keyboard of Nick Hibma: >> >>> And as to the author: Writing docu while you are implementing something >>> might work in a commercial environment where you want to be able to >>> market something before it's sell-by date, but for hobbiests who >>> basically spend the odd evening doing something, it is too much hassle. >> >> In case FreeBSD wants to enter commercial environments, we have to behave >> like behaving in commercial environments. >> >> I know that it is current behaviour, much easier and obviously a commonly >> accepted thing that code, subsystem and/or changes are not and need not >> to be documented, but this is not a reason in itself for not changing this. >> >> Also, i think that the argument Mike and others use: "don't complain for a >> lack of things, contribute!" - which i use and used all the time - is not >> valid for this issue: at least i can't contribute because i don't understand >> things (now someone could argue, that i'm wrong here ...). >> >> The last thing i want is a flamewar on this topic and i don't write this >> because i want to piss onto someones shoes. And i don't write about a >> man page for "ls" or "more" but a fundamental change in FreeBSD's inner >> architecture. > > Writing software in one's spare time is a case of triage. When I have a > day or two to spend working on FreeBSD, I have to make a choice on what > most needs doing and if that is a choice between technical writing or > designing an algorithm to fix the current limitations of driver detach and > KLD unload, I don't think the technical writing is going to win. > > People must also bear in mind that the most important target release for > this software is 4.0 which isn't scheduled until next year. I am certain > that the documentation situation will improve before that release. Doug, before you get the wrong impression, I don't think anybody's criticizing you. My intention was to raise the awareness of the importance, not of low-level documentation, but of "this is why we did it this way, and this is how to use it" kind of documentation; much of it could be in mail messages, but it's stuff which only the authors can really explain. Greg -- See complete headers for address, home page and phone numbers finger grog@lemis.com for PGP public key To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe cvs-all" in the body of the message