incubator-wave-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Pablo Ojanguren <pablo...@gmail.com>
Subject Re: Proposal - Documentation storage
Date Tue, 28 Apr 2015 15:18:49 GMT
+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/alternative (inline, None, 0 bytes)
View raw message