cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Andrew C. Oliver" <acoli...@apache.org>
Subject Re: [Fwd: Re: Good Software/Documentation was Re: I need your advice]
Date Sun, 28 Jul 2002 22:05:27 GMT
For clarification:

http://www.laputan.org/mud/mud.html#BigBallOfMud

Tom Klaasen wrote:

> 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 (sic).".
>
> 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>  ;-)
>
> tomK
>
>
>
> Andrew C. Oliver wrote:
>
>> This is TOTALLY true.
>>
>> ------------------------------------------------------------------------
>>
>> Subject:
>> Re: Good Software/Documentation was Re: I need your advice
>> From:
>> Brian Goetz <brian@quiotix.com>
>> Date:
>> Sun, 28 Jul 2002 12:17:21 -0700
>> To:
>> Lucene Developers List <lucene-dev@jakarta.apache.org>
>>
>>
>>> 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>
>>
>>
>>
>>  
>>
>> ------------------------------------------------------------------------
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
>> For additional commands, email: cocoon-dev-help@xml.apache.org
>>
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
> For additional commands, email: cocoon-dev-help@xml.apache.org
>
>




---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org


Mime
View raw message