cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Tom Klaasen <>
Subject Re: [Fwd: Re: Good Software/Documentation was Re: I need your advice]
Date Sun, 28 Jul 2002 20:16:52 GMT
This is, of course, a 2-sided knife:

I've lived quite a few projects where the programmers stated "We need 
more time to document all this, before we should make the next step". 
The answer of The Powers That Be is then "F*ck the documentation, we've 
got a deadline to meet. Do the doco afterwards. And while we're on the 
subject: do the analysis afterwards also. Will save us a lot of time 

The programmers are already the easiest to blame if a project doesn't 
succeed. Just because they're the last in line. Don't join that party, 
it becomes very frustrating.

In the mean time, I hope the programming business will follow after the 
soccer business (in Belgium at least): if your team doesn't score, fire 
the coach, not the players who're picking their noses ;-)

</you-just-stepped-on-my-toe-which-is-too-long-right-now-mode>  ;-)


Andrew C. Oliver wrote:

> This is TOTALLY true.
> ------------------------------------------------------------------------
> Subject:
> Re: Good Software/Documentation was Re: I need your advice
> From:
> Brian Goetz <>
> Date:
> Sun, 28 Jul 2002 12:17:21 -0700
> To:
> Lucene Developers List <>
>>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:   <>
>For additional commands, e-mail: <>
>To unsubscribe, e-mail:
>For additional commands, email:

To unsubscribe, e-mail:
For additional commands, email:

View raw message