+1
Yes I would also like to have a nightly build of the documentation from
trunk.
Additionally we should have a nightly build of the current production
branch (2.x in our case).
A build of the docs on release is also good but I think more important
is the branch as this allows us to fix problems in the documentation
after a release.
Christian
Am 17.06.2011 13:23, schrieb Achim Nierbeck:
Hey,
I like that idea of a nightly build on documentation :-)
If we get this easily integrated on our karaf.apache.org
with the right hint that it's the last documentation from trunk.
Voila done :-)
regards, Achim
2011/6/17 Guillaume Nodet<[email protected]>:
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
--
--
Christian Schneider
http://www.liquid-reality.de
Open Source Architect
Talend Application Integration Division http://www.talend.com
