Hi Andrew,
I think you missed my point.
Of course, I think doco is very important. My rant was just triggered by
>ostracize and fire programmers that
>don't write documentation up to the level of their code
I know a lot of programmers who started their career as good documentation-writing
guys, but who have been told time and again to omit "that nasty habit of documentation
writing". It is not the programmer's mind that has to be changed, but the ones of the
persons above him.
A lot of the projects that I was talking about, turned out to "the programmer didn't
program what I told him to!". Of course not, because there was nothing told to him
because "analysis is a waste of time".
I guess I'm just frustrated lately because it's always the programmer's fault if a
project isn't delivered on time and doesn't meet the requirements. It's never the
analyst whom the programmers asked "give me something decent to work with", nor the
project manager who was told "we really need to write some documentation".
So I agree with you that we have to develop a cultural revolution. However, I don't
think we should ostracize (I should look that word up ;) ) and fire _the programmers_,
but _the people above his head_.
Of course, in an OSS environment, "the programmers" equal "the people above his head",
so I guess you're right in the Cocoon case ;-)
tomK
------------------------
[EMAIL PROTECTED] wrote:
------------------------
>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 ;-)
>>
>>
>> ;-)
>>
>> tomK
>>
>>
>>
>> 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: [EMAIL PROTECTED]
>>> For additional commands, email: [EMAIL PROTECTED]
>>>
>>
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: [EMAIL PROTECTED]
>> For additional commands, email: [EMAIL PROTECTED]
>>
>>
>
>
>
>
>---------------------------------------------------------------------
>To unsubscribe, e-mail: [EMAIL PROTECTED]
>For additional commands, email: [EMAIL PROTECTED]
>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, email: [EMAIL PROTECTED]
