You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cocoon.apache.org by "Andrew C. Oliver" <ac...@apache.org> on 2002/07/28 21:24:08 UTC
[Fwd: Re: Good Software/Documentation was Re: I need your advice]
This is TOTALLY true.
Re: [Fwd: Re: Good Software/Documentation was Re: I need your advice]
Posted by "Andrew C. Oliver" <ac...@apache.org>.
And do these "meet the deadline at all cost" screw documentation
projects ultimately succeed?
Furthermore do they ultimately generate quality over time as one more
layer gets wrapped up on
another layer and duplication happens until the entropy is increadible?
Do the deadlines get easier
or harder to meet?
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 <br...@quiotix.com>
>> Date:
>> Sun, 28 Jul 2002 12:17:21 -0700
>> To:
>> Lucene Developers List <lu...@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:
>> <ma...@jakarta.apache.org>
>> For additional commands, e-mail:
>> <ma...@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
Re: [Fwd: Re: Good Software/Documentation was Re: I need your advice]
Posted by "Andrew C. Oliver" <ac...@apache.org>.
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 <br...@quiotix.com>
>> Date:
>> Sun, 28 Jul 2002 12:17:21 -0700
>> To:
>> Lucene Developers List <lu...@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:
>> <ma...@jakarta.apache.org>
>> For additional commands, e-mail:
>> <ma...@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
Re: [Fwd: Re: Good Software/Documentation was Re: I need your advice]
Posted by Tom Klaasen <to...@pandora.be>.
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 <br...@quiotix.com>
> Date:
> Sun, 28 Jul 2002 12:17:21 -0700
> To:
> Lucene Developers List <lu...@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: <ma...@jakarta.apache.org>
>For additional commands, e-mail: <ma...@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