lucene-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Brian Goetz <br...@quiotix.com>
Subject Re: Good Software/Documentation was Re: I need your advice
Date Sun, 28 Jul 2002 19:17:21 GMT
> 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.


--
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