@Ali, submitted today On 15 May 2015 at 05:12, Ali Lown <a...@lown.me.uk> wrote:
> @Evan: That PR looks fine to me. > One thing: Have you submitted an ICLA to Apache? It seems like it > would be a good idea to do at some point, as you are likely to > continue making not-insignificant changes to this repo. > > @Yuri/Others: How do we want to handle PR reviews? > I propose doing it the same way as on review-board, of leaving > comments on the system as appropriate. > Do we want to wait for multiple committers to say LGTM? > > I propose that at the moment, whilst the documentation repo is being > built up, that we just commit the PRs after looking over them for > sanity, and then lock it down a bit once stabilized to the current > code base? > > To avoid stalling this progress any longer, I will commit Evans PR > within the next 24hrs unless someone says otherwise. > > Ali > > On 9 May 2015 at 13:55, Evan Hughes <ehu...@gmail.com> wrote: > > For Pull request > > > > On 9 May 2015 at 17:12, Evan Hughes <ehu...@gmail.com> 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 <a...@lown.me.uk> 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 <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 > >>> >> >> > >> >> >> > >>> >> >> > >> >> >> > >>> >> >> > >> >> > >>> >> >> > >> > >>> >> >> > > >>> >> >> > >>> >> > >> > >> > > >
