[CentOS-docs] Docs strategy and tactics [RFC]

Fri Mar 13 00:31:22 UTC 2015
kunaal jain <kunaalus at gmail.com>

As I discussed earlier with you, I am very much excited about this
idea, bringing a new user friendly standard of writing as well as
accessing the documentation.

A couple of queries,

The author writes up in markup language -> possibly host the content
on github -> discussion over the content on mailing list -> changes to
be done -> changes done
-- seems fine till here. We define a markup language, style to be
followed, author writes in this style.

Now the main part is preparing for target location and delivering.
-- If it has to be pushed to upstream, our tool chains converts the
document according to the upstream guidelines, push it.

When we are pushing to upstream repo, we don't care about what they do
with it, we just convert the content according to their guidelines and
push it.
-- All good here.

When git.centos.org is involved, we have to actually deal with the
pushed content too. Right now centos.org/docs hosts content from RHEL.
We have to generate the centos.org/docs from our repo.
-- Is it right? Major change in how centos.org/docs work is required.

-- Aren't we too much depending on github for these tasks? Any
alternatives here?

We promote the content using existing channels of our centos, and
possibly upstream channels if content is pushed to them.
-- All good here.

Is the workflow I discussed in line with yours Karsten? I already have
a couple of tools in mind for this but lets leave that thing to my
GSOC proposal discussion with you.

It would be nice to bring technical requirements too in this discussion.

Regards,
Kunaal Jain