[CentOS-devel] Regarding GSoC project : Documentation Toolchain

[Sankarshan Mukhopadhyay]

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>