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 Tue, 28 Apr 2015 14:40:38 GMT
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