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 Fri, 24 Apr 2015 23:59:50 GMT
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