本文来自于公司内部的一个分享。 在文档方面，对内的一些接口文档主要是用swagger来写的。虽然可以在线测试，比较方便。但是也存在着一些更新不及时，swgger文档无法导出成文件的问题。 在对外提供的文档方面：我主要负责做一个浏览器端的一个js sdk。文档还算可以github地址，所以想把一些写文档的心得分享给大家。

1. 衡量好文档的唯一标准是什么？

Martin(Bob大叔)曾在《代码整洁之道》一书打趣地说：当你的代码在做 Code Review 时，审查者要是愤怒地吼道：

“What the fuck is this shit?”
“Dude, What the fuck！”

等言辞激烈的词语时，那说明你写的代码是 Bad Code，如果审查者只是漫不经心的吐出几个

“What the fuck?”，

那说明你写的是 Good Code。衡量代码质量的唯一标准就是每分钟骂出“WTF” 的频率。

衡量文档的标准也是如此。

2. 好文档的特点

  • 简洁：一句话可以说完的事情，就不要分两句话来说。并不是文档越厚越好，太厚的文档大多没人看。
  • 准确: 字段类型，默认值，备注，是否必填等属性说明。
  • 逻辑性: 文档如何划分？ 利于查看。
  • demo胜千言: 好的demo胜过各种字段说明，可以复制下来直接使用。
  • 读者心: 从读者的角度考虑, 方法尽量简洁。可以传递一个参数搞定的事情，绝对不要让用户去传两个参数。
  • 及时更新: 不更新的文档比bug更严重。
  • 向后兼容: 不要随意废弃已有的接口或者某个字段，除非你考虑到这样做的后果。
  • 建立文档词汇表：每个概念只有一个名字，不要随意起名字，名不正则言不顺。
  • 格式统一：例如时间格式。我曾见过2017-09-12 09:32:23, 或2017.09.12 09:32:23或2017.09.12 09:32:23。变量名user_name, userName。
  • 使用专业词语：不要过于口语化

3. 总结: 写出好文档要有以下四点

  1. 逻辑性：便于查找
  2. 专业性: 值得信赖，质量保证
  3. 责任心：及时更新，准确性，向后兼容
  4. 读者心：你了解的东西，别人可能并不清楚。从读者的角度去考虑，他们需要什么，而不是一味去强调你能提供什么。

4. 写文档的工具

  • markdown: 方便快捷，可以导出各种格式的文件
  • swagger: 功能强大，需要部署，不方便传递文件

5. markdown 工具推荐

  • 蚂蚁笔记 这是我正使用的。
    • 全平台（mac windows ios）有客户端，和浏览器端
    • 笔记可以直接公布为博客
    • 支持独立域名
    • 标签很好用
    • 支持思维导图
    • 支持历史记录
  • cmd-markdown
  • 有道云笔记

6. 文档之外

公司有个同事，我曾问他使用什么搜索一些技术文档，他说用百度。作为一个翻墙老司机，我惊诧的问他：你为什么不用谷歌去搜索。他说他不会翻墙。我只能呵呵一笑。

自从有一次搜索：graph for x^8 + y^8，我就决定不再使用百度了。你可以看一下两者的返回结果有什么不同。

总之：有些鸟儿是关不住的 他们的羽毛太鲜亮了。