Date: Wed, 23 Jun 1999 08:35:52 +0930 From: Greg Lehey <grog@lemis.com> To: Chuck Robey <chuckr@picnic.mat.net> Cc: Mike Smith <mike@smith.net.au>, hm@hcs.de, dfr@nlsystems.com, peter@FreeBSD.org, cvs-committers@FreeBSD.org, cvs-all@FreeBSD.org Subject: Documentation (was: cvs commit: src/sys/isa sio.c) Message-ID: <19990623083551.P76907@freebie.lemis.com> In-Reply-To: <Pine.BSF.4.10.9906221404080.393-100000@picnic.mat.net>; from Chuck Robey on Tue, Jun 22, 1999 at 02:11:01PM -0400 References: <199906220823.BAA01443@dingo.cdrom.com> <Pine.BSF.4.10.9906221404080.393-100000@picnic.mat.net>
next in thread | previous in thread | raw e-mail | index | archive | help
On Tuesday, 22 June 1999 at 14:11:01 -0400, Chuck Robey wrote: > On Tue, 22 Jun 1999, Mike Smith wrote: > >>> >>> Anyway, i don't think you are asking for too much - of what use is a shiny >>> new design of a new subsystem in the very basic FreeBSD architecture if just >>> some handful few people knew how it works and how to use it ? >> >> Gosh, that would make it just like every other shiny new subsystem. >> >> Folks, just cut the carping and write your own documentation. The >> architects can't, and won't write it for you. It has never happened >> that way (anywhere, on any project), and it never will. Documentation >> is written after the fact, by someone else. > > Well, I don't think it'll ever be too popular, but I know for a fact > (cause I saw it personally) that new projects (or at least the ones I > saw) at Tandem, before they were bought by Compaq, began with the docs > people writing how things were *supposed* to work. As the programmers > modified things, the docs people were there step by step, making sure > the docs said the same thing. > > I felt like I was in fantasyland. The point Mike shuld have made was > that this is a volunteer project, and there is *never* any way to force > someone to do something. The correct way to get something done, if you > want it done, is to do it yourself. If you can't do it yourself, if and > when th eoppurtunity presents, offer to do all you can to be of help, > but never, ever think you can make up silly rules saying someone else > *must* do something. > > Did you ever try to move something by *pushing* on a rope? Pulling > works much better. Complaining that someone else didn't do it, in a > volunteer project, is pushing on a rope. Well, I started this thread, though that's not me that Mike anonymized above. My statement was "it would be nice if...". The fact is that the original authors of the software are in the best position to document it, *if* they have the will to do so. They don't have to document every bit and byte, but it helps if they can explain the rationale behind what they're doing (like abstracting the "is configured" bit into a macro, and describing who should be allowed to mess in the private parts of the config routines). Agreed, in a volunteer project there's no way to force people to do this, but a consensus of "what's right" can help. 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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19990623083551.P76907>