如何写好技术文档?

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

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

clipboard.png

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

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

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

“What the fuck?”,

clipboard.png

那说明你写的是 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: 功能强大,需要部署,不方便传递文件
阅读 3.8k

洞香春
前端知识记录
3.6k 声望
1.1k 粉丝
0 条评论
你知道吗?

3.6k 声望
1.1k 粉丝
宣传栏