[CentOS-docs] Docs strategy and tactics

[杨 垒]

Hi,

I am interested in doing this project in GSoC and I’ve filed a proposal.

I’m really fascinated by this idea. Previously I translated the docs of Ghost to Chinese on GitHub, and found that GitHub is a great place to store and write docs. Contributors fork the docs repo on GitHub, modify it / create new article and send a PR. Then we can discuss the PR on GitHub just like on a mailing list, but in a way much more friendly to new comers. So contributors don’t have to learn to use mailing list and complicated doc tools just in order to contribute a single how-to article.

The Ghost team has their whole documentation site hosted on GitHub:Pages (http://docs.ghost.org <http://docs.ghost.org/>). GitHub:Pages is backed by Jekyll, which is triggered when new commit is merged, and afterwards generates the site using the MarkDown file. I think we can use this idea, too. This can help reduce the complexity of the project. The head job of arranging and generating a website from raw doc contents can be done by using such static site generators like Jekyll, and we can focus on providing the contributors with easy and lightweight way of contributing. I have proposed some ideas of improving UX in my proposal.

About syncing: since GitHub provides web hooks for projects, we can just monitor the web hook and sync for new changes accordingly. It should be a straightforward way. And about pushing the content to upstreaming projects, we can tag the new articles with its relevant projects. The tagging process is done on GitHub, where we can discuss about the article. The server program uses these tags to determine which projects should this article be pushed to. It is really awesome if documentations of open-source project are joined to a network and contents can be shared in the network.

Thanks!

————
Lei Yang
School of EECS, Peking University
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.centos.org/pipermail/centos-docs/attachments/20150329/4d09033c/attachment.html>