如何写好技术文档?

mengbo 发布于2019-08-21 17:27 / 596人阅读

摘要：衡量文档的标准也是如此。及时更新不更新的文档比更严重。写文档的工具方便快捷，可以导出各种格式的文件功能强大，需要部署，不方便传递文件

本文来自于公司内部的一个分享。
在文档方面，对内的一些接口文档主要是用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: 功能强大，需要部署，不方便传递文件

GPU云服务器云服务器如何写好python 如何学习区块链技术 java如何读入文档区块链技术如何应用

文章版权归作者所有，未经允许请勿转载,若此文章存在违规行为，您可以联系管理员删除。

转载请注明本文地址：https://www.ucloud.cn/yun/89525.html

如何写好技术简历 —— 实例、模板及工具

摘要：在线简历生成工具，可以导出。技巧目前写简历的方式有两种普遍被认可，一种是一种是。培养新人和带团队其他项目项目该项目是，使用技术，完成功能。阅读原文点击查看简历模板。工欲善其事必先利其器，这是自古以来的道理，所以如果想找到一份好的工作，一定要先整理一份好的简历。模板写简历首先要有一个好的模板，我们做技术的不同于 UX,UED，我们不需要那么花哨，但是也需要整洁干净。好的模板能让你的...

sunnyxd 2019-08-19 10:53 评论0 收藏0
PHPer面试指南-程序员如何写好一份简历？

摘要：本书的地址程序员的简历在求职的时候，尤为重要，简历就是销售自己的明信片，一份优秀的简历，能为你带来更多的面试机会。扩展阅读程序员简历应该怎么写面试时，如何向公司提问本书的 GitHub 地址：https://github.com/todayqq/PH...程序员的简历在求职的时候，尤为重要，简历就是销售自己的明信片，一份优秀的简历，能为你带来更多的面试机会。我自己写了不少了简历，...

tabalt 2019-06-28 18:19 评论0 收藏0
作为前端开发，如何写好一个简历

摘要：项目地址需求来源通常在各个招聘网站，我们填写完一些信息后，网站就可以帮助我们生成一个很不错的简历。但是作为一名开发者，尤其是前端开发者，可能对这种简历并不满意。，前端开发神器。最后，为了保护隐私。背景前一阵子，闲下来便开始着手做一个一直想做的东西--resume。经过几天业余时间的折腾，终于做出了一番模样。Github项目地址：https://github.com/eternity...

abson 2019-08-29 11:14 评论0 收藏0
作为前端开发，如何写好一个简历

摘要：项目地址需求来源通常在各个招聘网站，我们填写完一些信息后，网站就可以帮助我们生成一个很不错的简历。但是作为一名开发者，尤其是前端开发者，可能对这种简历并不满意。，前端开发神器。最后，为了保护隐私。背景前一阵子，闲下来便开始着手做一个一直想做的东西--resume。经过几天业余时间的折腾，终于做出了一番模样。Github项目地址：https://github.com/eternity...

KunMinX 2019-08-22 10:36 评论0 收藏0