Re: Javadocs: need basic package information

[Sylvain Wallez <sy...@anyware-tech.com>]

Bernhard Huber wrote:

> hi,
>
>>> i think writing a single packages.xml is better than maintaing 84 
>>> package.html files.
>>
>>
>> IMO, a centralized XML file may not be better as far as keeping it up 
>> to date is concerned :
>> - people may often forget to update a central file far away from the 
>> source files.
>> - will people really go inside a large XML file containing 89 
>> toplevel elements to update a single package description ? I think no.
>
>
> hmmm, i'd like to disagree.
> somehow it comes down to question who will most likely write the 
> package docs.
> Programmers? than package.html is better
> NonProgrammers, or NotOriginalProgrammers than package.xml is better.
> But I see your point of view.


This raises an interesting point : you seem to imply that the Cocoon CVS 
is divided in areas that belong to particular individuals or group of 
individuals, and that "strangers" to an area cannot modify what's in it.

Introducing such distinctions can be IMO very damageable to the dynamics 
of group development. NonProgrammers have the absolute right to document 
what's in the "src/java" directory, and they even should be encouraged 
to do it since everybody knows that programmers are often not good or 
lazy at writing docs.

This is my particular case, and I personally have absolutely no problem 
if someone adds some javadoc or package.html to some code that I've written.

>>> * add a packages.dtd ala faq.dtd
>>
>> I don't like neither constraining the content : package.html, as its 
>> name states, accepts any html markup. Javadoc extracts the first 
>> sentence to build the package summary table, but the file can contain 
>> a detailed design description of the package, including tables, 
>> images, etc. Sure, we don't have such detailed package.html now, but 
>> constraining the content will definitely prevent it...
>
> hmmm, as of today there is nearly no package.html at all.
> using a single package.xml my identation is to make this kind of 
> documentation available for the cocoon documentation. using a single 
> package.xml helps to achieve this, as far as i see. 


Something I dislike and makes me reluctant to write docs is having to 
write them in XML format (be it xdoc or something else). With 
package.html, I can just start Mozilla composer and start writing using 
a wordprocessor-like GUI.

> moreover i think that in most case programmers tend to write only some 
> class javadoc, and a second person having a bit more distance will 
> write the additional docs -- i know it from my own experiences 
> claiming to add javadoc documentation, don't doing it, and adding it 
> to foreign code missing it. :-) 


I have a similar experience. One is supposed to understand the code he 
writes (if not then there's a real problem ;-), and that's why we often 
don't document enough our own code. When reading poorly documented 
foreign code, one makes an effort to understand that code, and then 
documenting it is a way to share this effort and avoid it to others.

But this should occur in the same source files, that we are all, 
Programmers and NonProgrammers, responsible for.

Sylvain

-- 
Sylvain Wallez                                  Anyware Technologies
http://www.apache.org/~sylvain           http://www.anyware-tech.com
{ XML, Java, Cocoon, OpenSource }*{ Training, Consulting, Projects }



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

Re: Javadocs: need basic package information

[David Crossley <cr...@indexgeo.com.au>]

Stefano Mazzocchi wrote:
> Sylvain Wallez wrote:
> > Bernhard Huber wrote:
> >>>> i think writing a single packages.xml is better than maintaing 84 
> >>>> package.html files.
> >>>
> >>> IMO, a centralized XML file may not be better as far as keeping it up 
> >>> to date is concerned :
> >>> - people may often forget to update a central file far away from the 
> >>> source files.
> >>> - will people really go inside a large XML file containing 89 
> >>> toplevel elements to update a single package description ? I think no.
> >>
> >> hmmm, i'd like to disagree.
> >> somehow it comes down to question who will most likely write the 
> >> package docs.
> >> Programmers? than package.html is better
> >> NonProgrammers, or NotOriginalProgrammers than package.xml is better.
> >> But I see your point of view. 
> > 
> > This raises an interesting point : you seem to imply that the Cocoon CVS 
> > is divided in areas that belong to particular individuals or group of 
> > individuals, and that "strangers" to an area cannot modify what's in it.
> > 
> > Introducing such distinctions can be IMO very damageable to the dynamics 
> > of group development. NonProgrammers have the absolute right to document 
> > what's in the "src/java" directory, and they even should be encouraged 
> > to do it since everybody knows that programmers are often not good or 
> > lazy at writing docs.
> > 
> > This is my particular case, and I personally have absolutely no problem 
> > if someone adds some javadoc or package.html to some code that I've 
> > written.

This thread seems to have gone off on a tangent.
I do not think Bernhard was alluding to any such schism.
Rather he was trying to address the reality - at the
moment most programmers are not bothering to provide
even minimal documentation. So we need to make it
easier for both the programmers and the people who
are trying to help.

> And I would personally be *very* irritated by any other view on this 
> subject. I mean: once the code is into our CVS is not yours anymore its 
> *ours*. It's "cocoon community"'s which means that there will not be 
> *areas* where others are not allowed to work or should feel 
> uncomfortable in entering and changing.
> 
> Nobody with commit access (no matter *why* or *how* he/she got commit 
> access) should be scared/uncomfortable about modifying *any* part of 
> CVS. In fact, that's exactly why we have CVS in the first place: so that 
> people know that rollback is always possible and they don't feel afraid 
> of modifying stuff.
> 
> I'm very serious: any behavior that will even slightly suggest feelings 
> of code ownership from a committer will be considered *very* seriouly as 
> an obstacle to the evoulution of this project and *won't* be tollerated.
> 
<snip/>

> I think that javadocs (and docs, in general) should have a little 
> skeleton provided by who actually wrote the code and later 
> edited/modified/extended by others.... this is because sometimes
> the original author might take too many things for granted.

That is all that we have been trying to say here.

Actually, i would like us to turn the "should" into "must".
It is vital to at least provide some skeleton, otherwise
the poor people who to try to follow will get frustrated
and give up.

I would like to see something akin to John/Ovidiu clever
check-jars.xsl which breaks the build if a description
is not present.

> But I want to stress one point: the barrier for document writing is 
> high, too high, this year I'm going to make a serious effort to lower 
> that barrier.

We all look forward to that. The burden of adding the missing
documentation to Cocoon is overwhelming. If the project is not
very careful, then it is going to scare off the few who are
trying to rectify it.

--David



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

Re: Javadocs: need basic package information

[Stefano Mazzocchi <st...@apache.org>]

Sylvain Wallez wrote:
> Bernhard Huber wrote:
> 
>> hi,
>>
>>>> i think writing a single packages.xml is better than maintaing 84 
>>>> package.html files.
>>>
>>>
>>>
>>> IMO, a centralized XML file may not be better as far as keeping it up 
>>> to date is concerned :
>>> - people may often forget to update a central file far away from the 
>>> source files.
>>> - will people really go inside a large XML file containing 89 
>>> toplevel elements to update a single package description ? I think no.
>>
>>
>>
>> hmmm, i'd like to disagree.
>> somehow it comes down to question who will most likely write the 
>> package docs.
>> Programmers? than package.html is better
>> NonProgrammers, or NotOriginalProgrammers than package.xml is better.
>> But I see your point of view.
> 
> 
> 
> This raises an interesting point : you seem to imply that the Cocoon CVS 
> is divided in areas that belong to particular individuals or group of 
> individuals, and that "strangers" to an area cannot modify what's in it.
> 
> Introducing such distinctions can be IMO very damageable to the dynamics 
> of group development. NonProgrammers have the absolute right to document 
> what's in the "src/java" directory, and they even should be encouraged 
> to do it since everybody knows that programmers are often not good or 
> lazy at writing docs.
> 
> This is my particular case, and I personally have absolutely no problem 
> if someone adds some javadoc or package.html to some code that I've 
> written.

And I would personally be *very* irritated by any other view on this 
subject. I mean: once the code is into our CVS is not yours anymore its 
*ours*. It's "cocoon community"'s which means that there will not be 
*areas* where others are not allowed to work or should feel 
uncomfortable in entering and changing.

Nobody with commit access (no matter *why* or *how* he/she got commit 
access) should be scared/uncomfortable about modifying *any* part of 
CVS. In fact, that's exactly why we have CVS in the first place: so that 
people know that rollback is always possible and they don't feel afraid 
of modifying stuff.

I'm very serious: any behavior that will even slightly suggest feelings 
of code ownership from a committer will be considered *very* seriouly as 
an obstacle to the evoulution of this project and *won't* be tollerated.

>>>> * add a packages.dtd ala faq.dtd
>>>
>>>
>>> I don't like neither constraining the content : package.html, as its 
>>> name states, accepts any html markup. Javadoc extracts the first 
>>> sentence to build the package summary table, but the file can contain 
>>> a detailed design description of the package, including tables, 
>>> images, etc. Sure, we don't have such detailed package.html now, but 
>>> constraining the content will definitely prevent it...
>>
>>
>> hmmm, as of today there is nearly no package.html at all.
>> using a single package.xml my identation is to make this kind of 
>> documentation available for the cocoon documentation. using a single 
>> package.xml helps to achieve this, as far as i see. 
> 
> 
> 
> Something I dislike and makes me reluctant to write docs is having to 
> write them in XML format (be it xdoc or something else). With 
> package.html, I can just start Mozilla composer and start writing using 
> a wordprocessor-like GUI.

I hear you. I hear you. This year things will change, believe me.

>> moreover i think that in most case programmers tend to write only some 
>> class javadoc, and a second person having a bit more distance will 
>> write the additional docs -- i know it from my own experiences 
>> claiming to add javadoc documentation, don't doing it, and adding it 
>> to foreign code missing it. :-) 
> 
> 
> 
> I have a similar experience. One is supposed to understand the code he 
> writes (if not then there's a real problem ;-), and that's why we often 
> don't document enough our own code. When reading poorly documented 
> foreign code, one makes an effort to understand that code, and then 
> documenting it is a way to share this effort and avoid it to others.
> 
> But this should occur in the same source files, that we are all, 
> Programmers and NonProgrammers, responsible for.

I think that javadocs (and docs, in general) should have a little 
skeleton provided by who actually wrote the code and later 
edited/modified/extended by others.... this is because sometimes the 
original author might take too many things for granted.

But I want to stress one point: the barrier for document writing is 
high, too high, this year I'm going to make a serious effort to lower 
that barrier.

-- 
Stefano Mazzocchi                               <st...@apache.org>
--------------------------------------------------------------------



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