On Fri, Jun 17, 2011 at 12:28, James Strachan <[email protected]> wrote: > On 17 June 2011 11:16, Christian Schneider <[email protected]> wrote: >> Hi James, >> >> first thanks for your explanations. >> >> Am 17.06.2011 11:14, schrieb James Strachan: >>> >>> On 17 June 2011 09:19, Christian Schneider<[email protected]> >>> wrote: >>>> >>>> I know that I have proposed this before and then got the answer that this >>>> was discussed already. Still I have the feeling that everybody dislikes >>>> the >>>> current way we build our website.... so again a try :-)... >>> >>> I'm not sure you realise how much dislike there is for wikis? >>> >> I did not realize but I am starting to see :-) I only saw the >>> >>> Wikis don't help committers and don't help users (as you end up with >>> crap everywhere from different versions - or worse documentation for >>> stuff thats not even released yet); all just in case we hope one day >>> someone will turn up and dump a load of useful stuff in the wiki (that >>> never really happens). >> >> That is true help from people outside the project is rare. >>> >>> Incidentally I'm even finding the argument that a wiki is the easiest >>> way to get contributions to have less and less value these days since >>> github. Its actually easier for a total newbie to come along, fork an >>> apache project's git repo on github.com, edit some text files& do a >>> pull request than it is to pester folks for write access to the wiki >>> first before they can even begin to contribute anything. The wiki has >>> a much larger barrier to entry than github. >> >> Github would be a great way to improve the documentation workflow for karaf. >> You would not >> need to open a jira issue to make a change and apply patch. Sadly we are >> stuck with subversion. > > Sure - the sooner we can ditch subversion at Apache the better. > However still the easiest way to get new documentation contributions > today at Apache is to get folks to fork the apache repos at github. > Then asynchronously do the ICLA stuff; not block on the ICLA first. > > > >>> Imagine for a second, you are a newbie - you've seen some issue or >>> have an idea for a little page; with github 2 clicks, 20 seconds later >>> you're editing the file in question or writing the new file then >>> firing off the pull request and getting on with your life doing >>> something else. With a wiki you try editing; doesn't work, so you >>> shoot off an email for access then wait. Then after a random time >>> period of hours to days you get more mails then at some point later, >>> you get the ability to login again to the wiki and hopefully you can >>> now edit the page. By the time you get access you've probably >>> forgotten what you were gonna do in the first place :) >> >> The process of getting rights for the wiki is a problem of course. But it is >> necesary as we need the icla to accept contributions. >> That may also be a big problem with github. You send a pull request but that >> opens a big problem with IP issues. I think a pull request >> does not include that the user declares that he has the rights on the code >> he submits and may donate them to apache. In fact it does not even say he >> donates the code at all. >> So for example offering dual licenses later is a problem. I think this is a >> big issue with github. I am not sure how important this is for documentation >> though. > > We need the ICLA before we can merge into our repo. However thats a > completely separate issue to the potential new contributor being able > to actually create their contribution in the first place. The ICLA > stuff can be done in parallel after their initial contribution and it > really doesn't matter if it takes weeks to do (which it usually does > anyway). Apache committers are the only ones who merge the github > changes to the Apache repos - so there is zero issue of IP here. > > Whats important is folks can contribute quickly and easily with > minimum delay or red tape. We're all busy; if you have to wait 2-3 > weeks before you can add a line of text to a document; you're gonna > find something else to do quite frankly. Waiting weeks for an ICLA > does not make it easy for newbies to contribute. With github they can > make their contributions immediately; folks can immediately see it and > comment on it. Then in parallel work can commence on getting the ICLA > in place so the changes can be merged to Apache. Indeed while the ICLA > is being processed the user can make more contributions. When the ICLA > is done then a committer can merge in whatever documentation changes > they've made.
Over the last 5 years, I've rarely seen people contributing a lot to the doc without being or becoming committers. I don't want to change a technical decision based on the fact that people *might* need something, but rather what people actually need. You are a committer, so you can access / modify the documentation without any problems. So what are your real problems with the current solution ? We can easily set up nightly uploads or even an hourly cron job (though given the change rate, i think a nightly one should be sufficient). If you need an editor, you always find some software I think such as http://www.labnol.org/software/wysiwyg-wiki-editor/18062/ though I tend to use the "mvn jetty:run" which works quite well as you can see your changes immediately. The main problem is that we've been asked by infra to get rid of confluence, so I certainly don't want to think about getting back to confluence unless infra retracts. > > -- > James > ------- > FuseSource > Email: [email protected] > Web: http://fusesource.com > Twitter: jstrachan, fusenews > Blog: http://macstrac.blogspot.com/ > > Open Source Integration and Messaging > -- ------------------------ Guillaume Nodet ------------------------ Blog: http://gnodet.blogspot.com/ ------------------------ Open Source SOA http://fusesource.com
