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 Tue, 28 Apr 2015 23:53:43 GMT
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/alternative (inline, None, 0 bytes)
View raw message