This is TOTALLY true.
--- Begin Message ---
> 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:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
--- End Message ---
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, email: [EMAIL PROTECTED]
