On Fri, Jun 5, 2015 at 7:55 PM, Lei Yang yltt1234512@gmail.com wrote:
Our GSoC project is not very similar with a conventional doc toolchain. Its goal is to lower the barrier for new comers to contributor. Especially for those short-form how-to docs. Here is the original idea (http://wiki.centos.org/GSoC/2015/Ideas#docs-toolchain) for your reference.
Thanks for the link to the project concept. From the point-of-view of a peripheral participant in the upstream documentation communities of Fedora, OpenStack and Gluster my take on 'lowering the barrier' is around creating a system where a casual contributor can write, commit and publish content that is automatically rendered on to the live site.
Of course, this description tends to abstract the concept of a community of reviewers, workflow tooling and actual governance (eg. who can sign off on patches/contribs etc). But it does provide enough sweeping generalities to begin to look at things.
Taking that into consideration, we think that we should make use of github as that’a a platform that almost all potential contributors are familiar with. We don’t want to involve many command line executions. So we suppose that users make PR on github. However, at the same time, we don’t want to fully rely on a third party service like github, so we choose to store the original git repo on git.c.o. Pull requests happen on github, and changes are synced back to git.c.o after reviewing. Finally the doc is built based on git.c.o. That’s the workflow.
A number of upstream projects are choosing AsciiDoc/Markdown and github for various obvious reasons. One of which being making it easy for contributors to use lightweight editors (eg. https://atom.io/) or, familiar daily ones (eg. vi/emacs) to write the content without minimal requirements to learn a lot of tags/semantics.
The workflow you mention is logically sound. Although I cannot fathom where usage of a bugzilla instance fits in. You are probably using github.com as the back-up/archival repo with g.c.o being the primary one. That's somewhat odd, but I don't have anything against that plan.
To implement this, we need to integrate github and git.c.o. One of the steps is to provide a place where staff can review the changes and choose to accept the contribution. First we planed to use bugzilla, but in the discussion with Karsten and in the discussion on this list, we learned that using bugzilla will add extra burden to maintain it, so we might switch to bugs.centos.org. Using which platform is still to be discussed, and we may have a meeting on #centos-devel.
And this is where I am still puzzled. Bugzilla is a defect tracking/ticketing tool. It really doesn't lend itself to be a patch review tooling. Why would you be interested in modifying or,writing plugins for Bugzilla to do this? Are there no other tools/systems which can get this review component done?
Our project is aimed at short-form how-to docs and lowering the barrier, so conventional workflows might not work well in our project.
While your project might be enabling short-form docs you'll have to consider that it should make it easy to maintain the state of content. Stale or, out-of-sync content is a bigger problem than no content. And it is possible that you lay down a framework that is adopted across CentOS for all documentation.