From owner-freebsd-hackers Tue Jun 22 1:45:35 1999 Delivered-To: freebsd-hackers@freebsd.org Received: from dingo.cdrom.com (castles519.castles.com [208.214.165.83]) by hub.freebsd.org (Postfix) with ESMTP id 90F29151CF; Tue, 22 Jun 1999 01:45:29 -0700 (PDT) (envelope-from mike@dingo.cdrom.com) Received: from dingo.cdrom.com (localhost [127.0.0.1]) by dingo.cdrom.com (8.9.3/8.8.8) with ESMTP id BAA01553; Tue, 22 Jun 1999 01:42:06 -0700 (PDT) (envelope-from mike@dingo.cdrom.com) Message-Id: <199906220842.BAA01553@dingo.cdrom.com> X-Mailer: exmh version 2.0.2 2/24/98 To: Greg Lehey Cc: Mike Smith , hm@hcs.de, dfr@nlsystems.com, peter@FreeBSD.org, cvs-all@FreeBSD.org, FreeBSD Hackers Subject: Re: All this and documentation too? (was: cvs commit: src/sys/isa sio.c) In-reply-to: Your message of "Tue, 22 Jun 1999 18:02:52 +0930." <19990622180252.J76907@freebie.lemis.com> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Date: Tue, 22 Jun 1999 01:42:05 -0700 From: Mike Smith Sender: owner-freebsd-hackers@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.ORG > And they might, too. phk has frequently expressed a desire to either > write documentation on existing systems, or at least help others do > so. No offence meant, but we can see how much of this has actually materialised. > > It has never happened that way (anywhere, on any project), > > Of course it has. It's just uncommon in the FreeBSD environment. In > many large projects, you don't do any code until you have a clear > definition of what you're going to do. It's uncommon in _most_ environments. Or perhaps tech writers exist for some other purpose? > > and it never will. > > My father never had a computer, and his father never did, so I never > will have one. What an argument. The circumstances aren't comparable. > > Documentation is written after the fact, by someone else. > > That's the worst kind of documentation. In fact, most UNIX > documentation is written by the authors. After the fact, admittedly. In fact, most Unix documentation is never written, being my original point. > Hopefully the change of subject line and recipients will get some more > representative views on this subject. Perhaps I should have been clearer; the sort of documentation that the original set of plaintiffs were asking for is the mythical "describe everything as it was, is and will be, and make it constantly representative and up to date". These are the same people that will complain about disparities between any extant documentation and reality, as well as carp incessantly about the lack of some form of documentation other than what already exists ("why isn't there a permuted index?" "where's the sanskrit translation?" "my cat can't read _this_!"). As always, complaining about the _lack_ of something is the wrong approach for this project. Step up and fill the gap, or expose yourself to criticism for failing to do so. There has to be a way to make a verb from Brett Glass' name, but I'm sure you get the point. -- \\ The mind's the standard \\ Mike Smith \\ of the man. \\ msmith@freebsd.org \\ -- Joseph Merrick \\ msmith@cdrom.com To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-hackers" in the body of the message