文档

本文来自于公司内部的一个分享。 在文档方面，对内的一些接口文档主要是用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. 总结: 写出好文档要有以下四点 逻辑性：便于查找 专业性: 值得信赖，质量保证 责任心：及时更新，准确性，向后兼容 读者心：你了解的东西，别人可能并不清楚。从读者的角度去考虑，他们需要什么，而不是一味去强调你能提供什么。 4. 写文档的工具 markdown: 方便快捷，可以导出各种格式的文件 swagger: 功能强大，需要部署，不方便传递文件 5....