lucene-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Andrew C. Oliver" <acoli...@apache.org>
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:   <mailto:lucene-dev-unsubscribe@jakarta.apache.org>
>For additional commands, e-mail: <mailto:lucene-dev-help@jakarta.apache.org>
>
>
>  
>




--
To unsubscribe, e-mail:   <mailto:lucene-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:lucene-dev-help@jakarta.apache.org>


Mime
View raw message