cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject RE: [Proposal] review of sitemap component documentation
Date Wed, 24 Nov 2004 12:49:46 GMT

let me chip in. First: big hooray to David for proposing a plan for actual
documentation writing! 
Now: Start doing it! 
I see this thread end in a discussion on where to write the docs, where to
put the administrative table. Too bad. Every programmer on this list agrees
that code should be refactored if it improves quality, why not apply this to
documentation as well?
Yes, put the documentation as JavaDoc in the components. Advantage: it's
close to the code so people are more likely to update the docs when updating
the code. And it can always be taken out and put somewhere else if that
serves future needs better, but at least it's there!

So, go ahead, make your table. Great idea. 
If you do it in xdoc, beware that you will end up the administrator of the
table (integrating commits from non-committers). If you put it in wiki, and
you don't trust the backup, you simply make a local copy on a regular basis.
I'd say, put it in the wiki. Now that you have to register before being able
to edit, it's less likely to be changed by script kiddies.

Please just start.

Just my 2c.

Bye, Helma

> -----Original Message-----
> From: David Crossley [] 
> Sent: Wednesday, 24 November, 2004 12:52
> To:
> Subject: Re: [Proposal] review of sitemap component documentation
> Ralph Goers wrote:
> > David Crossley wrote:
> [snip]
>  >
> >> People who help are going to need to get their
> >> hands dirty in the xdocs and java code sources anyway.
> > 
> > I believe only committers can check in changes to xdocs and 
> java code.
> > There are several folks who aren't committers who, I 
> believe, would like 
> > to help out.
> Non-committers can send patches to xdocs or java code.
> They would have a local copy of the coordination
> table too.
> I will get started with it being an xdoc. If it becomes
> obvious that there is a big benefit to a wiki page,
> then we can move it there later.
> --David

View raw message