On Jul 29, 2016, at 1:16 PM, James Perkins <jperkins@redhat.com> wrote:

On Fri, Jul 29, 2016 at 6:42 AM, Carl Harris <ceharris414@me.com> wrote:
This has probably already been mentioned somewhere in this thread, but a related advantage to an asciidoc (or similar) approach using git, is that you can more easily take documentation contributions in the form of pull requests.

This is something I didn't consider. Thank you for pointing it out. Out of curiosity is there a reason you don't want to just update the document itself?

Apart from the issue of needing permission to do so, as I contributor I would feel more confident about suggesting a revision through a pull request, as opposed to committing a revision. Someone more familiar with the documentation would be able to ensure that conventions are appropriately followed, that the revision doesn't change the semantics in a way that is incorrect or inappropriate, etc. Basically, all the same benefits of any code review, but applied to documentation.

Having used a couple of open source products with freely editable documentation wikis, I'd say that even a minimal process of reviewing and merging changes is more likely to result in a consistent and useful document than simply allowing community edits. Again, just my 2 cents.