程序员如何写好技术文档

互联网发展很快，以前程序员一个人能干的活现在慢慢的被细分成多人协作，常见的职位有UI、UE、产品、前端、测试、后端、DBA，PE。但是没有哪个职位是专门负责写文档的，所有文档都是各个岗位的人兼职在做，毕竟大家都识字写两篇wiki不难。程序员可能会写接口文档，PM可能会写产品文档，UE可能会写交互文档，但并不是每个人都能写好文档。

以前去面试，有的HR会问我工作这么多年最大的成就是什么？这个问题很不好回答，不能装逼也不能太谦虚。我都会说，业余时间我把公司历年的文档全部收集整理了一遍……每次说这些的时候HR都忍不住点头，仿佛在说这小伙子社会主义核心价值观满分。我们离职后之前写的代码、设计的架构在2-3年内肯定会被慢慢的迭代替换，但是留下的文档公司会永久保存，这样想就会让你有写文档的动力。当然我写文档是有私心的，我很不喜欢写代码的时候被打断，特别是问你权限怎么申请，机器怎么申请，域名怎么申请……有文档之后直接扔wiki链接就行。

写文档这件事很重要，也是一项很有前途的技能。但是为什么没有专业的人去做这样一件专业的事情呢？我猜测是大家都不重视，好比我是程序员里文档写的最好的和我是程序员里代码写的最快的哪个更有份量？说了这么多终于要引入正题---如何写好技术文档？怎样的技术文档才算优秀？

先看看这份文档：http://rust-lang.github.io/book/first-edition/index.html

中文版看这里：https://kaisery.gitbooks.io/rust-book-chinese/content/content/README%20%E4%BB%8B%E7%BB%8D.html

这份文档是迄今为止我见过的 最优秀 的文档，主要优点有下面几个：

1. 结构清晰；

   所谓结构清晰就是用户能马上找到自己要查找的知识点在哪，分类清晰。有些文档爱用模棱两个的词，比如“1. 常见问题”，“2. 热点问题”,"3. 高频问题"。我有十万火急的事情，你来告诉我我到底是要先看哪个？

2. 循序渐进；

   先从最简单的开始，然后慢慢深入。比如我们学习Java，一开始Hello World都还没跑起来就先说配置文件要怎么写，Java一大堆的xml配置文件老司机都看的眼花缭乱更别说新手，这种文档让人直接从想了解到放弃。

3. 引人入胜；

   把能吸引人的地方展示出来，比如Unity 3D默认就带一个设计精良的游戏Demo，一看到就有学习的兴趣。如果提供的是Web API除了有详细的文档外还应该直接能在浏览器里模拟出一个可调用的Demo，而不是看着API文档还需要不停的尝试，不停的踩坑才能调通。

看完文档之后肯定会有人觉得这个文档写的也就那样啊，没什么特别的。那我接着介绍。

这是Rust编程语言的官方文档，Mozilla基金会专门花钱聘请来的文档编辑大神Steve Klabnik，Steve Klabnik是唯一一个因为文档写的好，写进Rust核心八人组的，然后一直负责撰写和维护Rust的各种文档。在程序员里靠写PPT为生的人很多，但是靠写文档为生的人非常少，基本上是经济独立有名气的程序员会写文章挣点打赏。

Rust lang发展了这么多年文档风格都非常统一，开发者也非常买账，流畅的阅读体验为Rust的学习添加了不少乐趣。假如有人拿了Apple或者Google的钱帮忙写文档，写的很差或者有瑕疵大家都不会说啥，毕竟商业公司什么样的人都有。如果拿了基金会的钱，文档写的有瑕疵那就说不过去了，以程序员们喷人的水平不出一天……所以说拿这份文档当作文档撰写的蓝本再合适不过。

最后贴上Steve Klabnik的GitHub：https://github.com/steveklabnik

更多相关文章请移步我的博客-原文链接：程序员如何写好技术文档

喜欢编程的朋友可以关注我的个人公众号，保证每周三篇原创。

程序员编程日志