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 > >> >> > >> >> >> > >> >> > >> >> >> > >> >> > >> >> > >> >> > >> > >> >> > > >> >> > >> >
