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 <[email protected]> wrote:
> This is a proposal for ....
>
>
> TL;DR
>
>
