From owner-freebsd-current Sun Aug 12 20:42:28 2001 Delivered-To: freebsd-current@freebsd.org Received: from dragon.nuxi.com (dsl092-013-169.sfo1.dsl.speakeasy.net [66.92.13.169]) by hub.freebsd.org (Postfix) with ESMTP id 1B1C137B406 for ; Sun, 12 Aug 2001 20:42:26 -0700 (PDT) (envelope-from obrien@NUXI.com) Received: (from obrien@localhost) by dragon.nuxi.com (8.11.5/8.11.1) id f7D3gLo08457; Sun, 12 Aug 2001 20:42:21 -0700 (PDT) (envelope-from obrien) Date: Sun, 12 Aug 2001 20:42:21 -0700 From: "David O'Brien" To: Joe Kelsey Cc: current@freebsd.org Subject: Re: Documentation in FreeBSD Message-ID: <20010812204221.A8432@dragon.nuxi.com> Reply-To: obrien@freebsd.org References: <15223.16537.621443.350921@zircon.zircon.seattle.wa.us> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline User-Agent: Mutt/1.2.5i In-Reply-To: <15223.16537.621443.350921@zircon.zircon.seattle.wa.us>; from joe@zircon.seattle.wa.us on Sun, Aug 12, 2001 at 07:51:05PM -0700 X-Operating-System: FreeBSD 5.0-CURRENT Organization: The NUXI BSD group X-Pgp-Rsa-Fingerprint: B7 4D 3E E9 11 39 5F A3 90 76 5D 69 58 D9 98 7A X-Pgp-Rsa-Keyid: 1024/34F9F9D5 Sender: owner-freebsd-current@FreeBSD.ORG Precedence: bulk List-ID: List-Archive: (Web Archive) List-Help: (List Instructions) List-Subscribe: List-Unsubscribe: X-Loop: FreeBSD.ORG On Sun, Aug 12, 2001 at 07:51:05PM -0700, Joe Kelsey wrote: > OK, so we have beaten the psm and keyboard code to death. The entire > point that I have been trying to make in this discussion is that it is > imperative to document design decisions somewhere that is likely to > survive changes in maintainer. ... > What I am pleading for is nothing more than any commercial software > house requires of its programmers. And *PAYS* its programmers to do. This is the point you are missing. If you were to commercially sponsor some design docs, I'm sure we can get them written. > Certainly, we could adopt some sort of standard practice to > embed design comments in the code. I personally prefer to over-comment > as it is hard to determine exactly what someone needs 5 years from now > to fix a problem. Send patches. You wanted some of the PSM comments added to the code -- send a patch that adds the ones you think would have helped you. -- -- David (obrien@FreeBSD.org) To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-current" in the body of the message