On Jul 29, 2016, at 1:16 PM, James Perkins
<jperkins(a)redhat.com> wrote:
On Fri, Jul 29, 2016 at 6:42 AM, Carl Harris <ceharris414(a)me.com
<mailto: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.
carl