[ic] Re: [interchange-cvs] interchange - docelic modified 5 files

Andreas Grau agrau at esquat.com
Wed Mar 29 09:19:34 EST 2006


On Wed, 29 Mar 2006 15:38:33 +0200
Stefan Hornburg <racke at linuxia.de> wrote:

> > 
> > This is good news. When will this be ?
> 
> Obviously when it is ready.

My question was not loaded in any way. And now that the announcement
has been made, I did think there's a timeframe behind.

> 
> > 
> > Other than that, and I don't want to be a pain in the neck (although I
> > probably am), my questions remains open: _For which reason_ do you take
> > the comments out. You could *copy* them, for example. Or you could even
> > *add* to them. Are you going to delete *all* inline documentation ?
> 
> Yes, he is going to do that. Any duplication is a bad thing in terms of
> programming.

What you call duplication, I call redundancy. And during the process
of creating a new set of documentation, I would have valued redundancy quite
high.

> 
> > 
> > I am meaning not WHY (because there the answer is clear: it has been
> > decided), I am asking "for what purpose".

I understand that there is a decision that has been taken. Is there are
short formula about the "for what purpose". As it is now obviously too
late to reverse the decision, this may be a moment to explain what led
to it.

> > 
> > There once was a time, when generating documentation from inline
> > comments was state of the art, because one found that programmers, who
> > are known to notoriously avoid writing documentation, prefer to
> > document as they code, instead of keeping two different files in
> > sync.
> 
> Better to actually do something in a consistent way then pretend to be "state of
> art". I'm pretty sure that the Interchange developers who already spent a
> substantial amount of time with Interchange documentation understand and
> support Davor's documentation project.

I haven't changed my opinion too much since last mail exchange here on
the list: There are the few Interchange developers who don't need the
documentation, and many others who need them to get going.


I wanted to understand the [perl] tag. Result :
DESCRIPTION

BEHAVIOR

This tag does not appear to be affected by, or affect, the rest of Interchange. 


I needed some background on [if] - Not even listed.


It's simply that I don't understand the priorities of Davor's
documentation project, as you call it.

> 
> The documentation effort definitely benefits from submissions and input,
> so don't get me wrong.
> 

No problem, Racke. And you point is well taken. Only that I don't have
a very high esteem on how this is done, so count on me for other areas.

Andreas


More information about the interchange-users mailing list