cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Crossley <cross...@apache.org>
Subject Re: [Proposal] review of sitemap component documentation
Date Thu, 25 Nov 2004 02:11:40 GMT
H.vanderLinden@MI.unimaas.nl wrote:
> Guys, 
> 
> let me chip in. First: big hooray to David for proposing a plan for actual
> documentation writing! 
> Now: Start doing it!

Yes, the only way with these things is for someone to start
and to enable others to help.

> 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?

I am not talking here about refactoring anything,
neither code nor docs, just building upon the system
that we already have. We need patches to existing
userdocs/generators/* and userdocs/transformers/* etc.
and patches to the corresponding java code.

This proposal is only addressing that portion
of our documentation, nothing else.

> 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!

Yes.

> 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).

As i have said a few times in this thread, various
committers can make patches to the xdocs and java src.
They can also patch the coordination table in xdocs.
Non-committers can provide patches.

> 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.

Thanks for your encouragement.

--David

> Just my 2c.
> 
> Bye, Helma
> 
> 
> 
>>-----Original Message-----
>>From: David Crossley [mailto:crossley@apache.org] 
>>Sent: Wednesday, 24 November, 2004 12:52
>>To: dev@cocoon.apache.org
>>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


Mime
View raw message