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

  1. 云栖社区>
  2. 博客>
  3. 正文

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

uyang 2016-03-19 14:09:25 浏览6103
展开阅读全文

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

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

  1. 运行easy_install安装sphinx和pip

     easy_install sphinx
     easy_install pip
    

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

  1. 在文档目录里,运行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.

网友评论

登录后评论
0/500
评论
uyang
+ 关注