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: [EMAIL PROTECTED] For additional commands, email: [EMAIL PROTECTED]
