incubator-wave-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ali Lown <...@lown.me.uk>
Subject Re: Proposal - Documentation storage
Date Thu, 30 Apr 2015 15:53:47 GMT
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
View raw message