For Pull request On 9 May 2015 at 17:12, Evan Hughes <[email protected]> wrote:
> I believe we should split the docs into: > > Documentation => Documents how to build the documentation and how to use > sphinx + ReST (mostly just an example and to help ease the transition) > manual => The user manual provided with the client (How to > make a wave, .....) > developer => Everything a developer would need, how to start the > server, how to build, how to contribute > api => How to build with the gadgets/robot api > protocol => All about the protocol specifications > > after the "Documentation" is built I will submit a pull request to the > main so you guys can see if you like it. > > On 6 May 2015 at 00:41, Ali Lown <[email protected]> wrote: > >> 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 <[email protected]> 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 <[email protected]> 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 <[email protected]> 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" <[email protected]> >> 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 <[email protected]>: >> >> >> >> >> >> > 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 <[email protected]> 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 <[email protected]> >> 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 <[email protected]> >> wrote: >> >> >> > >> > indeed and yea without a doubt >> >> >> > >> > >> >> >> > >> > On 25 April 2015 at 09:59, Ali Lown <[email protected]> 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 <[email protected]> >> >> 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 <[email protected]> >> >> wrote: >> >> >> > >> >> > >> >> >> > >> >> >> This is a proposal for .... >> >> >> > >> >> >> >> >> >> > >> >> >> >> >> >> > >> >> >> TL;DR >> >> >> > >> >> >> >> >> >> > >> >> >> >> >> >> > >> >> >> >> >> > >> >> >> >> > >> >> >> >> >> >> > >
