Return-Path: Delivered-To: apmail-jakarta-lucene-dev-archive@apache.org Received: (qmail 92615 invoked from network); 28 Jul 2002 19:22:06 -0000 Received: from unknown (HELO nagoya.betaversion.org) (192.18.49.131) by daedalus.apache.org with SMTP; 28 Jul 2002 19:22:06 -0000 Received: (qmail 9201 invoked by uid 97); 28 Jul 2002 19:22:28 -0000 Delivered-To: qmlist-jakarta-archive-lucene-dev@jakarta.apache.org Received: (qmail 9142 invoked by uid 97); 28 Jul 2002 19:22:26 -0000 Mailing-List: contact lucene-dev-help@jakarta.apache.org; run by ezmlm Precedence: bulk List-Unsubscribe: List-Subscribe: List-Help: List-Post: List-Id: "Lucene Developers List" Reply-To: "Lucene Developers List" Delivered-To: mailing list lucene-dev@jakarta.apache.org Received: (qmail 9123 invoked by uid 98); 28 Jul 2002 19:22:26 -0000 X-Antivirus: nagoya (v4198 created Apr 24 2002) Message-ID: <3D444462.1010503@apache.org> Date: Sun, 28 Jul 2002 15:22:10 -0400 From: "Andrew C. Oliver" User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.0; en-US; rv:1.0.0) Gecko/20020530 X-Accept-Language: en-us, en MIME-Version: 1.0 To: Lucene Developers List CC: cocoon-dev@jakarta.apache.org, poi-dev@jakarta.apache.org Subject: Re: Good Software/Documentation was Re: I need your advice References: <20020728115302.B4711@lx.quiotix.com> <4.2.2.20020728115924.02630c20@thinkalong.com> <20020728121721.B4936@lx.quiotix.com> Content-Type: text/plain; charset=us-ascii; format=flowed Content-Transfer-Encoding: 7bit X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N Brian Goetz wrote: >>Is there any reason to believe that something along the lines of >>literate programming will play a role in bridging the gap between >>good software, bad documentation? >> >> > >I have reason to believe the opposite, sadly. > >Java made an attempt to pick up on some of the principles of LP when >integrating JavaDoc into the source code. Unfortunately, the JavaDoc >has replaced, rather than supplemented, external documentation, and >most JavaDoc ranges from bad to worthless. And JavaDoc is really only >for reference; its a _terrible_ way to actually learn an API, although >that's how we all do it. > >I think the answer is cultural; ostracize and fire programmers that >don't write documentation up to the level of their code. (OK, this is >overstated by several notches, but you get the point.) When >programmers become embarrassed if they write bad (or no) >documentation, they'll write better documentation. > > > well said. I look forward to your article. >-- >To unsubscribe, e-mail: >For additional commands, e-mail: > > > > -- To unsubscribe, e-mail: For additional commands, e-mail: