Hi Guillaume,
I see the possible advantages of keeping the documentation in
subversion. The problem is that I think they are more academic than real.
Am 17.06.2011 10:59, schrieb Guillaume Nodet:
There are also lots of benefits of not using cwiki:
* ability to work offline (that's really a problem with confluence)
The ability to work offline is a real and great benefit of subversion.
* ability to experiment using branches
I am not sure if this will be used much. On the wiki this can still be
done by creating pages for the changes on branches and later replacing
the original page with it.
That is not a streamlined but works.
I think branches even cause a lot of effort. As most documentation
changes affect several versions you will have to keep the branches in sync.
Another problem is which branch to show in the web. trunk ? Last releaed
versions? All supported branches? I think this will rather confuse people.
* ability to version documentation easily
As I said in the other mail I think documentation has a different
lifecycle than the code. So I think keeping them together may even be a
bad idea after all. For example if there is an
error in the documentation you most times wil not want to wait for a
patch release to see the fix. You will rather want to see it asap.
Currently we show the manual of version 2.1.99-SNAPSHOT this clearly
shows that we do publish the documentation of the current release.
* ability to modify several pages at once
May be intersting sometimes for search and replace in all the documentation
* ability to better track contributions
To really track the contribution before people are committers you need
jiras. Btw a jira is the only way people can submit patches as of now.
So while this sounds good it means that for a fixed typo. You would need
to :
- create a jira issue
- Describe what you want to do
- Checkout the source.
- find the source file that corresponds to the web page
- Make the change
- Test the change with maven
- Create a patch
- submit the patch to jira
- Wait till someone takes the issue
The committer will:
- assing himself to the issue
- update the source
- apply the patch
- test with maven
- commit
Whoever sync the website will:
- update the source
- call a sync script
So I think these are about 16 steps. I think the time from idea to
visible change will be about 10 to 20 days. Three people are involved
typically.
In confluence the contributor does:
- click edit page
- make the change
- save
This takes seconds and only one person is involved.
If the change is bad someone will spot using the subscription and corect
the change.
On the last one, I actually think giving people modification rights is
not necessarily a good idea.
People should be able to become committers but simply contributing
doc. Do you monitor all the doc changes on cxf / camel made by non
committers ? And actually, how many modifications are we talking about
?
I too think that people should be able to become committers by changing
documentation. Tracking the changes in confluence is no big problem.
Using the subscription changes from someone will be highly visible. So
committers will notice and can vote for the person.
There is even a nice activity view for a contributor:
https://cwiki.apache.org/confluence/display/~christian+schneider
Btw talking about numbers. svnsearch tracks nicely how much was committed:
http://svnsearch.org/svnsearch/repos/ASF/search?from=20110301&path=%2Fkaraf%2Ftrunk%2Fmanual
So it seems we only had 18 commits to the manual since first of march. I
think this is not much.
Sadly I can not see the statistics in the wiki as I do not have the rights.
Last, we had a vote on that a few months ago, so please go read the
discussions, as Jean-Baptiste explained, we had some discussions and
came to a conclusion ... We were using cwiki until a few months.
I will read the discussion there. So perhaps if now is a bad time we
could simply revisit the decision in half a year and review if it was good.
Christian
--
--
Christian Schneider
http://www.liquid-reality.de
Open Source Architect
Talend Application Integration Division http://www.talend.com
