Hi,
With the Eclipse Winery project (part of SOA), I am developing at GitHub and want to provide ease editing of docs. Thus, I'm going for markdown.
First, I thought, that github-pages are a good idea, because
(i) they support markdown out of the box and
(iii) the documentation comes along with the code and can be updated along with a commit.
(iv) Possibility to use GitHub's pull request review system to ensure quality of the updates.
In case, however, a contributor wants to add text to github-pages, the IP process has to be kicked off: The documentation relies inside the "doc" folder of the source code repository. This causes load on the EMO IP team, which I'd like to reduce and not to increase. Thus, I decided for using the GitHub wiki page (i.e.,
https://github.com/eclipse/winery/wiki in the context of winery). See also
https://dev.eclipse.org/ipzilla/show_bug.cgi?id=13783I accept that the Wiki is not rendered that nicely (point ii), that the documentation is not at the same place as the code (point iii) and that I cannot use GitHub's pull request review system (point iv).
Since contributors are not allowed to edit the Wiki directly, the approach to get content in is via "git magic": The contributor clones the wiki locally, does the edits and pushes the changes to a git repository X. I fetch from X, review the changes and push the changes to the Eclipse.
Is this workflow intended? Acceptable? What do other projects do for their documentation. What is best practice?
When seeing
https://eclipse.org/che/, I think, I should generate a GitHub repository "winery-homepage", which uses Jekyll to generate the HTML files and then "push" the generated HTMLs to the Eclipse infrastructure. So, I could take the advantages of (i), (ii) and (iv).
WDYT?
Cheers,
