Outline Contributor Guide

[graphitefriction]

• Start by using existing content that has been pulled out of README (see Rework the README asciidoctor.js#71)
• Guide should be able to used unversally between all projects

[mojavelinux]

We also have a contributing guide in Asciidoctor core from which to draw ideas.

https://github.com/asciidoctor/asciidoctor/blob/master/CONTRIBUTING.adoc

I'd also like to look outside of the Asciidoctor project for good examples of a contributing guide.

One of the things I want have is a section at the top that welcomes everyone to contribute in whatever way they can. We don't want people to get the impression that contributing is limited to sharing code.

[abelsromero]

As mentioned here (PR22 of maven-plugin-examples), not only should this be used across project from a content point of view but technically.

Ideally, we should be able to reuse it without the need of copying it manually, but I’m not aware of a nice way to achieve that on github.
This makes me think if we should tackle first how to organize the documentation in a way that linking all documents across projects in a single deploy is possible. At least in a way that allows us to link common documents and publish all contents in the site, even if this means that link won’t work on github.
The easiest option is to move them to a single project, but I don’t see this as an viable option. That centralization model would mean a lot of work for the supervisor/merger of that repo.
Projects with this same issue I can think off are Groovy or Spring, do you it makes sense to look how they deal with it?

[mojavelinux]

I'm glad you are thinking about this problem.

I think the solution is automation. A computer can do very tedious boring tasks without ever complaining :) We would likely leverage the CI server to sync files when the master is updated. This might be an automatic pull request from the canonical source out to each of the repositories. When the step is automated, it doesn't count as copying in my book. And I can't see another easy solution since GitHub does not allow remote includes (or includes at all). So we make it a "pseudo-include" by materializing it upon change.

I think what we should be thinking about is designing this workflow. Imagine that we have decided on a canonical location. What happens next? How do we detect a change? How is the change propagated. etc. Once we get a strong idea of this workflow in theory, we can convert it to code. Let's make the CI servers work for it.