The repository is at https://github.com/apache/incubator-wave-docs, and is rather empty at the moment. I see no reason we shouldn't accept pull requests to this repo, so I suggest you use that workflow...
Sphinx sounds fine. Many people will be familiar with rest (it shares a lot with markdown but is more powerful) thanks to Python docs making use of it. Can we find any other volunteers for moving the docs out of confluence, as there is quite a lot to do....? Ali On 1 May 2015 at 04:03, Evan Hughes <ehu...@gmail.com> wrote: > I think sphinx would be a better option than jekyll for the documentation, > it does use restructured text instead of markdown but is more extensible > and can easily produce a pdf format compared to markdown. Gonna spin up my > own repo and see how it is, been looking at the syntax and it isn't that > bad. > > On 1 May 2015 at 01:53, Ali Lown <a...@lown.me.uk> wrote: > >> Okay. A new repository has been made: >> https://git-wip-us.apache.org/repos/asf?p=incubator-wave-docs.git >> >> I have requested github integration for it, so we can use pull >> requests if we would like to... >> >> Ali >> >> On 29 April 2015 at 00:53, Evan Hughes <ehu...@gmail.com> wrote: >> > I like the idea of also moving the website off of the cms but not sure if >> > it should be in same repository. Ill look into jekyll for the >> documentation >> > but theres also other build systems which might be better for us aka html >> > and pdf export. >> > >> > Go ahead with the repository for the documentation and well go from >> there. >> > Well need to transfer any issues in jira or deal with them during the >> > transition >> > On 29/04/2015 1:20 AM, "Pablo Ojanguren" <pablo...@gmail.com> wrote: >> > >> >> +1 Moving doc to git would be good, moreover if we update and improve >> it a >> >> litlle bit along the migration process (at least the organization). >> >> >> >> 2015-04-28 16:40 GMT+02:00 Ali Lown <a...@lown.me.uk>: >> >> >> >> > Yuri, >> >> > >> >> > I think the main reason to move is to make it easier for people to >> >> > make changes, over the existing confluence system. So I would have >> >> > though that improving the documentation is something people would be >> >> > more likely to do afterwards. >> >> > >> >> > I agree that opening some tickets where the documentation could be >> >> > improved does help highlight the problem, but it doesn't make it any >> >> > easier for people to fix. >> >> > >> >> > Ali >> >> > >> >> > P.s. Do you want me to do anything for RC9, or are you happy to submit >> >> > one? Are you waiting on me for anything still? >> >> > >> >> > On 28 April 2015 at 15:36, Yuri Z <vega...@gmail.com> wrote: >> >> > > Maybe it would be better to move in small steps. Like to go over >> >> current >> >> > > documentation and open tickets with requests for improvements >> wherever >> >> > > something is missing or not clear. >> >> > > >> >> > > On Tue, Apr 28, 2015 at 5:33 PM Ali Lown <a...@lown.me.uk> wrote: >> >> > > >> >> > >> Well, doesn't look like anybody else has much opinion. >> >> > >> >> >> > >> Shall I just raise a ticket for a new repo for this? >> >> > >> >> >> > >> It probably makes sense to put the whole website under it, rather >> than >> >> > >> using the combination of Apache CMS website + Confluence that we do >> >> > >> currently. We could just use Jekyll for both website and docs? >> >> > >> >> >> > >> Ali >> >> > >> >> >> > >> >> >> > >> On 25 April 2015 at 02:52, Evan Hughes <ehu...@gmail.com> wrote: >> >> > >> > indeed and yea without a doubt >> >> > >> > >> >> > >> > On 25 April 2015 at 09:59, Ali Lown <a...@lown.me.uk> wrote: >> >> > >> > >> >> > >> >> Hi Evan, >> >> > >> >> >> >> > >> >> +1 >> >> > >> >> >> >> > >> >> After giving this some more thought post the Hangout, I do think >> >> that >> >> > >> >> moving the docs to Git provides us with a measurable improvement >> >> over >> >> > >> >> the current situation - particularly with the ability to keep >> docs >> >> > >> >> synced with the releases via branches, and the reduced barrier >> to >> >> > >> >> entry for changing them. >> >> > >> >> >> >> > >> >> Would you be interested in leading the migration effort? >> >> > >> >> >> >> > >> >> Ali >> >> > >> >> >> >> > >> >> On 24 April 2015 at 05:59, Evan Hughes <ehu...@gmail.com> >> wrote: >> >> > >> >> > woops, my bad >> >> > >> >> > >> >> > >> >> > >> >> > >> >> > This is a proposal for the storage of documentation to be >> moved >> >> to >> >> > a >> >> > >> git >> >> > >> >> > repository instead of on confluence and leave confluence as a >> >> place >> >> > >> for >> >> > >> >> > other technical documents used by developers. >> >> > >> >> > >> >> > >> >> > *Confluence:* >> >> > >> >> > *The issues:* >> >> > >> >> > - contributors must ask for permission from the >> mailing >> >> > list >> >> > >> to >> >> > >> >> be >> >> > >> >> > given the privilege settings to edit/create pages >> >> > >> >> > - Simple revision history is kept but is more >> difficult >> >> to >> >> > >> easy >> >> > >> >> > transition documentation between wave release versions, more >> of a >> >> > >> running >> >> > >> >> > active document >> >> > >> >> > *The good:* >> >> > >> >> > * - *easily able to export to pdf and web formats >> >> > >> >> > - has an easy online rich editor >> >> > >> >> > >> >> > >> >> > *Git (markdown):* >> >> > >> >> > * The issues:* >> >> > >> >> > * - *setup as a new repository? a folder in current >> >> > repository? >> >> > >> >> > apache will need to be involved if a new repository is to be >> >> setup >> >> > >> >> > - exporting the markdown files into a meaningful >> >> > >> representation >> >> > >> >> > (web, pdf), many build systems exist but custom system can >> also >> >> be >> >> > >> >> written >> >> > >> >> > by our committers >> >> > >> >> > * The good:* >> >> > >> >> > * - *less of a roadblock, allows users to contribute >> more, >> >> > also >> >> > >> >> > allows new committers a trial at how to add commits using the >> >> > apache >> >> > >> >> > procedures >> >> > >> >> > - Highly customisable >> >> > >> >> > - Revision history and versions easily achieved for >> >> example >> >> > >> with >> >> > >> >> > branches (master, 0.4.x, 0.5.x, ....) >> >> > >> >> > >> >> > >> >> > *TL;DR* >> >> > >> >> > >> >> > >> >> > Confluence is a rich wiki but can limit the availability for >> >> > >> committers >> >> > >> >> to >> >> > >> >> > publish updates (need to ask permission, which isn't that >> hard) >> >> and >> >> > >> is a >> >> > >> >> > good place to store technical information for the project. >> >> > >> >> > A markdown written file structured documentation >> implementation >> >> is >> >> > >> more >> >> > >> >> > accessible to developers, follows a more natural flow and can >> be >> >> > >> highly >> >> > >> >> > customised and has great revision structure. >> >> > >> >> > >> >> > >> >> > *Relevant Jira Issues:* >> >> > >> >> > * - none* >> >> > >> >> > >> >> > >> >> > *Please express your opinions below and if enough feedback is >> >> > present >> >> > >> a >> >> > >> >> > vote from the mailing list should be called after the >> >> discussion. * >> >> > >> >> > >> >> > >> >> > >> >> > >> >> > On 24 April 2015 at 14:28, Evan Hughes <ehu...@gmail.com> >> wrote: >> >> > >> >> > >> >> > >> >> >> This is a proposal for .... >> >> > >> >> >> >> >> > >> >> >> >> >> > >> >> >> TL;DR >> >> > >> >> >> >> >> > >> >> >> >> >> > >> >> >> >> > >> >> >> > >> >> >>
