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:[EMAIL PROTECTED]> >For additional commands, e-mail: <mailto:[EMAIL PROTECTED]> > > > > -- To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
