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

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

解决问题

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

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

1. 运行easy_install安装sphinx和pip

    easy_install sphinx
    easy_install pip
   

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

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

参考资源

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