lucene-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Andrew C. Oliver" <>
Subject Re: Good Software/Documentation was Re: I need your advice
Date Sun, 28 Jul 2002 19:22:10 GMT
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: <>

View raw message