incubator-wave-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Evan Hughes <ehu...@gmail.com>
Subject Re: Proposal - Documentation storage
Date Sat, 09 May 2015 12:55:33 GMT
For Pull request

On 9 May 2015 at 17:12, Evan Hughes <ehugh1@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 <ali@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 <ehugh1@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 <ali@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 <ehugh1@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" <pablojan@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 <ali@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 <vega113@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 <ali@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 <ehugh1@gmail.com>
>> wrote:
>> >> >> > >> > indeed and yea without a doubt
>> >> >> > >> >
>> >> >> > >> > On 25 April 2015 at 09:59, Ali Lown <ali@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 <ehugh1@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
<ehugh1@gmail.com>
>> >> wrote:
>> >> >> > >> >> >
>> >> >> > >> >> >> This is a proposal for ....
>> >> >> > >> >> >>
>> >> >> > >> >> >>
>> >> >> > >> >> >> TL;DR
>> >> >> > >> >> >>
>> >> >> > >> >> >>
>> >> >> > >> >>
>> >> >> > >>
>> >> >> >
>> >> >>
>> >>
>>
>
>

Mime
  • Unnamed multipart/mixed (inline, None, 0 bytes)
View raw message