Eric, thanks for the wiki page, excellent work. While editing the wiki page Eric created I got to think more about the concrete ways in which the two approaches are different. Most of the documentation is generated by committers. Not ideal for at least two reasons. It doesn't scale first of all and any good coder could figure out what the code does and produce reasonably good documentation. An editor/technical writer could take it to the next level and make it great (much better than what we committers could come up with, I guess) The only problem is getting users which such skills interested enough to contribute.
With the current wiki based system it's fairly easy to make a change, press Preview and if you're happy with the result press Save. One cannot modify multiple pages in one transaction, but not a big issue. The big issue is that for IP related reasons we can only give edit karma to contributors who are willing to file the icla. It's a fair assumption that no one would bother to file an icla for minor contributions. With an SVN based system, in the absence of a CMS to automate it, it is a bit more involved to create the code, you have to build it, run it (hope you won't have port in use issues), but in the end you get a patch. I would think not many would bother to go through this for a minor contribution either. There are a number of advantages for the second approach. For once the doc and the code would be in one place, big advantage. Second, users would be able to have a copy of the camel site locally (or within the enterprise). Third, we won't have to rely on Confluence plugins for site generation and we have more power and flexibility there. Although I still believe the SVN based solution is a significant loss in terms of convenience, I believe less that it will be a significant deterrent for those who are really willing to contribute. We should probably go ahead and move in that direction now (but I still don't favor the 'instead of' idea). I see this as a major feature for 3.0 as well (reasons above). My $0.02 Hadrian On Nov 11, 2010, at 10:20 AM, Jon Anstey wrote: > Personally I would favor *instead of* (cause its probably more work to have > both...) but I want whats best for the community of course :) > > BTW I was poking around in svn and saw that Apache Ant also hosts their docs > in SCM http://svn.apache.org/repos/asf/ant/core/trunk/docs/ so we wouldn't > be the first or anything to do that... > > On Thu, Nov 11, 2010 at 11:28 AM, Hadrian Zbarcea <hzbar...@gmail.com>wrote: > >> Jon, >> >> Absolutely valid point. Are you saying that you'd like that *in addition >> to* a wiki way of updating documentation or *instead of*? >> >> Hadrian >> >> >> On Nov 11, 2010, at 8:29 AM, Jon Anstey wrote: >> >>> I think this thread is over but I just wanted to agree on a point Johan >> (and >>> probably others) made here. >>> >>> "Not to mention if you actually fix a bug and submit a patch you could >> fix >>> documentation in one feel swoop." >>> >>> That is an EXCELLENT point. In the past I've always put off writing any >> docs >>> for a code change (bad, I know..) partly because confluence is slow >>> and cumbersome and also because once the code fix has been made docs seem >>> lower priority... I think being able to do both in one commit would make >> doc >>> updates happen more often. I mean, sometimes it may be just that you >> renamed >>> an endpoint URI property so it may be a really simple change to the docs. >>> >>> On Wed, Nov 10, 2010 at 12:34 PM, Johan Edstrom <seij...@gmail.com> >> wrote: >>> >>>> I actually really liked the scalate project and writing the docs in >> IDEA, >>>> making a patch and tossing it in github. >>>> >>>> Offline editing also seems really nice for when you are on planes, in >>>> airports or hotels. >>>> Not to mention if you actually fix a bug and submit a patch you could >> fix >>>> documentation in one feel swoop. >>>> >>>> And with the possibility of editing and running Jetty locally - it was >>>> really easy. >>>> >>>> Just my .02, i'm one of those that like irc for the quick informal style >>>> over forums for example, >>>> I also really like svn/git since I have tooling around versioning et al. >>>> >>>> And yeah, making patches is "klunky" using diff and things like that. >>>> >>>> /je >>>> On Nov 10, 2010, at 8:52 AM, Hadrian Zbarcea wrote: >>>> >>>>> >>>>> On Nov 10, 2010, at 10:28 AM, James Strachan wrote: >>>>> >>>>>> On 10 November 2010 15:15, Daniel Kulp <dk...@apache.org> wrote: >>>>>>> On Wednesday 10 November 2010 9:59:11 am James Strachan wrote: >>>>>>>> On 10 November 2010 14:51, Daniel Kulp <dk...@apache.org> wrote: >>>>>>>>> >>>>>>>>> For most of the people on this list, it ISN'T a big deal. We deal >>>> with >>>>>>>>> svn and mvn every day. For others, it could be. >>>>>>>> >>>>>>>> Given 99% of all our documentation and web content is developed by >>>>>>>> committers or folks who are capable of editing text files and using >>>>>>>> git/svn, I'd rather use a system that helps the 99% be more >> effective. >>>>>>>> >>>>>>>> Maybe you should just help out this one CXF person & show them how >> to >>>>>>>> fork & commit to github (its very easy), then you can easily pull >>>>>>>> their commits from there? >>>>>>> >>>>>>> Umm.. no. Pulling branches from github is NOT, at this point, an >>>> acceptable >>>>>>> way of getting content into an Apache product. They would still >> need >>>> to >>>>>>> create a patch and attach it to JIRA with the "grant" checkbox >>>> checked. >>>>>> >>>>>> Whatever happens folks have to raise a JIRA and click the "grant" >>>> checkbox. >>>>>> >>>>>> I fail to see why a link to a specific commit (i.e. a link to a number >>>>>> of patches) is any less suitable than a number of patch files being >>>>>> attached in place to the JIRA. Got anything specific to back this up >>>>>> or is it just that we've not done it before? >>>>>> >>>>>> Patch files are a total PITA for both the person contributing and the >>>>>> person applying the patch. (They usually break, get out of sync, have >>>>>> whitespace issues and frequently have the wrong path information in >>>>>> them & often have problems with new/renamed/deleted files). >>>>>> >>>>>> If this discussion really is about being a "community issue" and >>>>>> making it easy for both folks to contribute and for committers to >>>>>> apply those contributions, I'd rather we figure out this issue of >>>>>> using links to git commits as an alternative to patch files on JIRAs - >>>>>> this could make a *massive* difference to both getting contributions >>>>>> and more effectively applying them IMHO. Helping scm-novices >>>>>> contribute to documentation (which they've never really done so far on >>>>>> Camel anyway) seems quite irrelevant in comparison. >>>>> I don't know if this is a scm-novices issues. We had contributions from >>>> not committers in the past. >>>>> Johan (before his commiter days) is one example, Steve Bate is another. >> I >>>> would rather ask them how likely would it be to contribute to doc if >> they >>>> had to co/edit/submit-patch, vs edit in-place wiki style. >>>>> I know they are not scm-novices. >>>>> >>>>> I am open to any alternative that would not raise the barrier to entry >>>> for documentation contributors and that's acceptable to the ASF. >>>>> >>>>> Hadrian >>>>> >>>>>> >>>>>> -- >>>>>> James >>>>>> ------- >>>>>> FuseSource >>>>>> Email: ja...@fusesource.com >>>>>> Web: http://fusesource.com >>>>>> Twitter: jstrachan >>>>>> Blog: http://macstrac.blogspot.com/ >>>>>> >>>>>> Open Source Integration >>>>> >>>> >>>> >>> >>> >>> -- >>> Cheers, >>> Jon >>> --------------- >>> FuseSource >>> Email: j...@fusesource.com >>> Web: fusesource.com >>> Twitter: jon_anstey >>> Blog: http://janstey.blogspot.com >>> Author of Camel in Action: http://manning.com/ibsen >> >> > > > -- > Cheers, > Jon > --------------- > FuseSource > Email: j...@fusesource.com > Web: fusesource.com > Twitter: jon_anstey > Blog: http://janstey.blogspot.com > Author of Camel in Action: http://manning.com/ibsen
