文档

如何为项目写文档、用什么写文档、如何方便的管理/更新文档，这是很多技术人员都要经常面对的一些问题。根据个人经验，程序开发类工作中我们涉及到的文档可能主要包括下面几类，

  • 函数/类的接口说明文档， 比如 XXX Framework API Documentation
  • 服务端接口说明文档，比如 Web Service API, Restful API 等
  • 使用指南、手册等说明文档，比如 Getting Start XXX, XXX Tutorial, XXX Guideline, XXX Manual 等
  • 设计相关文档，比如 数据库 ER 图、类图、时序图等（Enterprise Architect）

相关工具/平台

下面，我们将分别介绍一些常用的相关工具/平台

使用指南、手册等说明文档

此类文档内容多以大段文字说明为主，一般按章节进行内容组织，随着项目的不断成熟、演进，很多成熟项目的文档都会有相当篇幅；于此同时，出于格式、排版等需求，逐步形成了多种标记语言标准，常见的比如 TeX, DocBook, Markdown, reStructuredText, AsciiDoc 等。目前互联网项目中主要流行 Markdown, reStructuredText, AsciiDoc 等轻量级标记语言，Tex、DocBook 过于复杂，reStructuredText 主要在 Python 开发者中流行，Org-mode 主要以 Emacs 用户为主，Markdown 最为流行（由于 Markdown 过于简单，目前几大组织/公司分别定义了自己的 Markdown 扩展语法，比如 GitHub Flavored Markdown，MultiMarkdown，Markdown Extra，Pandoc Markdown 等）。

扩展阅读：

ReST（reStructuredText）

  • Sphinx Documentation，可能是 ReST（reStructuredText） 系的代表项目了吧，Python 开发，由于语法简单、功能强大，非常多的项目都使用 Sphinx 来生成项目文档（感受下?），跟他一起出现的还有 Read The Docs（开源文档生成的托管平台和社区，同时支持 reStructuredText 格式以及 Markdown 格式） 这位兄弟，关于他们之间的关系，可以看下这里；相关 PHP 项目示例，

Markdown

由于 Markdown 简单易读，只需要普通的文本编辑器就能够编辑，语法更是简单到每个人都可以在数分钟内学会，因此，作为一门 2004 年才被发明出来的轻量级标记语言，Markdown 很快便得到了诸如 Github，reddit, Stack Exchange, Bitbucket 等大量网站的支持。而伴随着 Github 旋风横扫整个开源界， git + Github + Markdown + Jekyll 组合更是成为互联网时代大量科技写作者甚至小部分文艺青年的主力生产力平台。

下面的表格对比了几款支持 Markdown 的主流文档工具之间主要特性的区别（实际区别可能与我所理解的有偏差）：

名称 自助托管—— 多语言文档 实时同步 静态 HTML 多版本
Read The Docs ✗ ✓ ✓ ✓ ✓
Peach ✓ ✓ ✓ ✓（可缓存） 计划中
Mkdocs ✓ ✗ ✗ ✓ ✗
GitBook ✓ ✓ ✓ ✓ ✗
Jekyll ✓ ✓（插件） ✓ ✓ ✓（不完美）

AsciiDoc

AsciiDoc 最初基于 Python 开发，其基本语法跟 Markdown 类似，例如以 = 开头作为标题、以 * 号开头作为列表项等，详细的语法说明可以看这里，但 AsciiDoc 比 Markdown 支持更多的格式，比如表格、文件包含等，同时 AsciiDoc 是 O’Reilly 的 Atlas 在线出版平台 的推荐语言，相当大部分的 Git 官方文档都使用了 AsciiDoc 格式。

扩展阅读：

DocBook

Tex

Tex 是由 Donald Knuth 创造的基于低级编程语言的电子排版系统，利用 TeX 能够对文章进行十分精美的排版，TeX 提供了一套功能强大并且十分灵活的排版语言，同时 TeX 系统是公认的数学公式排得最好的系统。

  • LaTeX - LaTeX（发音为“Lah-tech”或“Lay-tech”）是由 Leslie Lamport 开发的当今世界上最流行和使用最为广泛的TeX宏集。 把 LaTeX 放到最后是由于 TeX 语法的高门槛，导致除了专业的科学研究、出版领域，除了我们敬仰的那些大神们，在偏工程/应用类的普通码农界中没有真正大规模流行开来。

函数/类的接口说明文档

服务端接口说明文档

  • Swagger, Demo
  • Apiary - （推荐）Apiary.io平台具有协同设计、即时API模拟、快速生成源码、自动测试和代码调试的开源设计工具，最重要的是可以在线模拟测试，因为该平台具备模拟服务器测试服务，可以把设计好的程序在线测试、验证。
  • Apidoc, Demo
  • Slate - 创建好看的 API 文档，Travis-CI, Appium 等项目使用中，更多例子：Examples of Slate in the Wild
  • JSON-Schema
  • prmd - JSON Schema tools and doc generation for HTTP APIs
  • 如何编写 API 的文档？

设计相关文档