On Fri, Jun 5, 2015 at 7:55 PM, Lei Yang <yltt1234512 at 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. -- sankarshan mukhopadhyay <https://about.me/sankarshan.mukhopadhyay>