Markdown+Pandoc+Sphinx+ Git 协作写书式推进团队技术文章

让写技术文章成为大家的一种工作习惯和方式。

yestone_HD_1133212058_jpg_heading

解决问题##

促进个人，团队，大团队技术博客的建设：

1. 习惯成自然， 先要有习惯，然后才能成为自然。
2. 习惯要容易养成，利用技术人员写笔记做积累的特点和相应项目需要技术文档的特性，和工作紧密结合，让写文章就像写代码一样。
3. 寻找一种方便的方式将每个人以及项目的积累以标准整理输入。
4. 积少成多，建立机制自然的汇聚，让每个人是小溪，小团队是小河，大团队的ATA是我们的大江。
5. 思想和笔记需要一定的积累和加工，按照写书的思路，让大家有合作编辑和评审的参与感，才能有高质量的文章产出。

建议##

以MarkdownPad + Pandoc + Sphinx + Git的的标准方式推进，这是目前很多开源软件的技术文档的协作方式。

技术特点###

1. 以git管理文章内容，技术人员很习惯也也便于管理。

2. 以Markdown为文章格式，MardownPad等工具很适合大家本地编写。

3. Pandoc可以做各种格式的转换，比如输出层pdf。

4. Sphinx可以方便讲各种文章以书籍的格式整理，并产出高质量的在线阅读格式。

5. 很好的表格支持，markdown对table支持不够，sphinx对table以及自定义table有很强的支持。

具体可参考示范。

期望目标##

1. 每个人以这种方式做平时的技术笔记整理，让个人养成习惯。团队以这种方式像协作写书一样做团队技术博客文集，团队之间形成良性竞争，看哪个团队的文集产出和质量最高。

2. 这些产出都会输出到团队的ATA上，同时也能成为自身团队的技术积累。

3. 这种方式也可以向整个技术部推荐，进而成为集团内标准的技术文档管理规范。

如何更好的激励##

需要大家更多的意见...

示例和源码##

安装

1. 安装pandoc，http://www.pandoc.org/
2. 安装python和easy_install.

http://www.baidu.com/link?url=IYtjch8TRUjvhqpGEFAJgT7744EBFqyq5y3uT1w2PUbxk0DlSqQQ32Xok0C58F9fj-b7ySNDg99UmvI_BoKGMYnzkzhM8OBpu6_frWRQRRi&wd=&eqid=c14c359a00093e7e00000005565696ba

3. 运行easy_install安装sphinx和pip

   easy_install sphinx
   easy_install pip

这个过程有失败可以多试验几次。

4. 在文档目录里，运行make clean ; make html构建文档

_2016_03_19_15_26_21

参考资源##

Makedown 本地工具： MarkdownPad
Pandoc： www.pandoc.org（Sphinx 依赖）必须先安装。
Sphinx: http://sphinx-doc.org/ 具体参考Sphinx安装。 依赖python, pip, pandoc.