[wildfly-dev] One Doc to Rule Them All

[Carl Harris]

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



-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/wildfly-dev/attachments/20160729/58bd9c0e/attachment.html