Sylvain Wallez wrote:
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.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.
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.
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.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.
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 <[EMAIL PROTECTED]>
--------------------------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, email: [EMAIL PROTECTED]
