[EMAIL PROTECTED] 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:[EMAIL PROTECTED]
Sent: Wednesday, 24 November, 2004 12:52
To: [EMAIL PROTECTED]
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
