关于java:如何写好技术文档来自Google十多年的文档经验

本文大部分内容翻译总结自《Software Engineering at Google》第 10 章节 _Documentation_。另外，该书电子版近日曾经能够收费下载了 https://abseil.io/resources/swe_at_google.2.pdf，有趣味的同学能够下载翻阅下。首先申明，本问所说的文档不仅限于纯文本文档，还蕴含代码正文(正文也是一种非凡模式的文档)。

很多技术人本人十分鄙视技术文档的书写，然而又时常埋怨文档不欠缺、品质差、更新不及时…… 这种在程序猿间普遍存在的矛盾甚至曾经演变成了一个段子。

文档的重要性

高质量的文档对于一个组织或团队来说有十分多的好处，比方让代码和 API 更容易了解、谬误更少；让团队成员更专一于指标；也能够让一些手工操作更容易；另外如果有新成员退出的话有文档也会让他们更快融入……

写文档有比较严重的 收益滞后性，不像测试，你跑一个测试 case，它能立刻通知你是对还是错，它的价值马上就体现进去了。而写一份文档，随着工夫的推移，它的价值才会逐步体现进去。你可能只写一次文档，未来它会被浏览上百次、上千次，因为一份好的文档能够在将来替你向他人答复相似上面这些问题。

1. 为什么过后是这么决策的？
2. 为什么代码是这样实现的？
3. 这个我的项目里都有哪些概念？
4. ……

写文档同样对于写作者也有十分大的收益：

• 帮你构思规范化 API： 写文档的过程也是你扫视你 API 的过程，写文档时会让你思考你 API 设计是否正当，思考是否周全。如果你没法用语言将 API 形容进去，那么阐明你以后的 API 设计是不合理的。
• 文档也是代码的另一种展示： 比方你两年后回过头来看你写过的代码，如果有正文和文档，你能够很疾速了解代码。
• 让你的代码看起来更业余： 咱们都有个感觉，只有文档齐全的 API 都是设计良好的 API，尽管这个感觉并不完全正确，但这两者的确是强相干的，所以在很多人眼里，文档的欠缺度也成为掂量一个产品业余度的指标。

• 防止被反复的问题打搅： 有些问题你只须要写在文档里，这样有人来问你的时候你就能够让他间接去看文档了，而不是又给他解释一遍。

  为什么大多数人都不喜爱写文档？

  对于文档的重要性，每个技术人或多或少都晓得一些，但很多人还是没有写文档的习惯，为什么？除了上文中提到的文档的 收益滞后性 外，还有以下几点起因：

• 很多工程师习惯将写代码和写作割裂开，不仅仅是在工作上，而且在思想上就认为它们是齐全不相干的两项工作，这就导致好多人重代码不重文档。
• 也有很多工程师认为本人不善写作，索性就不写了。这理论是个偷懒的借口，写文档不须要富丽的辞藻、活泼的语言，你只须要将问题讲清楚即可。
• 有时候工具不好用也会影响的文档写作。如果没有一个很好的写作工具将写文档嵌入到开发工作流程中的话，写作的确会减少工作的累赘。
• 大多数人将写文档看做是工作的额外负担。我代码都没工夫写，哪有工夫写文档！，这其实是谬误的观点，文档尽管后期有投入，但能让你代码的前期保护老本大幅升高，磨刀不误砍柴工这个情理置信大家都还是能了解的。

如何产出高质量文档

既然了解了好文档的重要性，咱们如何保障在工夫的长河中保护好一份文档，这里有些相干的方法论，大家能够参考下。

像治理代码一样治理文档

对于如何写出好代码，整个技术圈曾经有好多教训的总结了，比方书籍《重构》《代码简洁之道》…… 针对各种编程语言，也有相干的标准，比方国外的 Google C++ 标准，国内的 阿里 Java 开发标准 等…… 但对于文档 仿佛相干的材料却很少。但实际上，不应该把文档和代码割裂开来，你能够简略粗犷地认为 文档其实就是用一种非凡语言书写的代码，这种语言就是人类的语言。这么想的话，实际上咱们很多在代码和工程中总结进去的教训，也能够间接用在文档中，比方：

• 有对立的标准
• 有版本控制
• 有明确的责任人保护
• 有变更 Review 机制
• 有问题的反馈和更新机制
• 定期更新
• 有掂量的指标(比方准确性，时效性)

明确你的读者是谁

写文档有一个很常见的谬误，那就是很多人文档都是写给本人看的，这种状况下就会导致你的文档只有本人或者和你有类似常识背景的人才能看懂，团队较小时这种问题还好，你们都做着相似的工作，所以也都能看懂文档。但当团队逐步壮大后，问题就会凸显进去，新人有时候有着和你不同的工作背景，甚至当初都做着不同的工作内容，这时候你之前写的文档他们就很难读懂了。

所以在写文档之前请明确你文档可能的读者会是哪些人，而后针对他们的特点着重关注如何能力让他们了解。当然，文档也不肯定要十分庄重和完满，只有能向你潜在的读者阐明问题即可。记住 文档是写给他人看的，不是给本人看的。

依据业余程度能够大抵将读者分为三种 老手、新手和专家，针对不同程度的人写作须要有侧重点。比方针对老手，你须要重点介绍下外面波及到的术语和概念，而后具体解说具体的的实现。相同，针对专家 你能够省去这些额定的信息。留神，这里没有严格的规范，因为有些文章老手会看，专家也会看，这里还是须要具体情况具体分析。

另外一种对读者分类的形式就是依据读者浏览文档的目标来分类，比方有人晓得本人遇到了什么问题，就是来找解决方案的。还有一批人只有一个简略的想法，但不晓得具体的问题。举个例子，以读数据库慢为例，前者曾经晓得数据库慢可能是因为数据量微小且没有加索引，解决方案很简略 加索引，这时候他可能须要晓得的是如何正确地加索引。而后者可能着重关注的是为什么读数据库会慢，这时候你可能须要额定重点介绍下数据库相干的原理。

清晰的分类

文档大抵能够分为以下几种类型，每种类型也有本人不同的特点和写作侧重点。

参考文档

参考文档也是大部分开发人员日常会应用和书写的文档，比方咱们应用某个框架或者工具，都会有 API 阐明文档，这就属于参考类文档。它并没有太多的要求，只有能向读者展现分明如何 应用 即可，但无需向读者讲明具体的实现。

注：参考文档并不仅限于 API 文档，还包含文件正文、类正文、办法正文，要求都是能精确阐明其用法。

设计文档

很多公司或者团队在我的项目开始前都要求有设计文档，设计是我的项目施行的第一步，所以在设计文档书写的过程中要求尽可能思考周全，例如该项目标存储、交互、隐衷……

好的设计文档应该蕴含以下几个局部：

1. 设计指标
2. 实现的策略
3. 各种利弊衡量和具体决策
4. 代替计划
5. 各种计划的优缺点

写设计文档的过程也你对整个我的项目做布局、思考可能呈现问题的过程，设计的越具体、思考的越多，将来遇到问题的可能性就会越小。

疏导类文档

疏导类文档也很常见，个别都是 Step by Step 的模式。比方咱们在应用某个框架或者工具的时候，个别都会有个疏导类的文档一步一步帮忙你疾速上手。大家 写疏导类文章大家非常容易犯的一个谬误就是预设了很多背景常识 。个别应用文档都是有开发者写的，他们都十分理解这个工具的相干的常识，所以习惯性的会认为， 啊 这个知识点很简略 用户也必定会吧 ，实际上用户不肯定会。这 实质上就是一种认知偏差，这种景象在跨团队合作 尤其是多端合作的时候也非常明显。

这类型的文档写作中，要求写作者尽可能站在用户的视角上思考，竭力避免出现和用户的认知偏差，力争每个步骤做到明确无歧义，每两个步骤之间做到严密连接。

概念性文档

当参考文档无法解释分明某些货色的时候，就须要概念性文档了，比方某个 API 的具体实现原理。其次要是为了裁减参考文档，而不是代替参考文档。有时候这和参考文档会有些内容反复，但次要还是为了更深层次的阐明某些问题、解释分明某个概念。

概念性文档也是所有文档中写作最难的，也是被浏览起码的，所以很多状况下工程师最容易漠视。而且还有另外一个问题，没适合的中央放，参考文档能够写代码里，落地页能够写我的项目主页里，概念性文档仿佛也只能在我的项目文档里找个不起眼的角落寄存了。

这类文档的受众会比拟广，专家和老手都会去看。另外，它须要强调概念清晰明了，因而可能会就义完整性(能够由参考文档补齐)，也有可能会就义准确性，这不是说肯定要就义准确性，只是该当分清主次，不重要的就没必要说了。

Landing pages(落地页)

Landing pages 就先简略翻译成落地页了，没想到啥失当的翻译词。比方一个团队或者我的项目的导航页，尽管没啥具体的内容，但应该蕴含其余页面的链接。比方你新入职一个团队，比拟成熟的团队都会扔给你一个文档，这个文档里蕴含罕用的工具、文档链接，这就是这个团队的落地页。
落地页的问题就是随着工夫的推移，页面可能会变的越来越乱，而且有些内容会生效，不过这些问题都好解决，做好定期的保护和整顿就行。
落地页的技术难度不高，但要求内容的有效性、完整性和分类清晰。

文档 Review

在一个组织内，光靠集体去保护文档是不行的，必须得借助群体的智慧。在一个组织外部，文档的变更也应该像代码的变更一样，须要被其他人 Review，以提前发现其中的问题并晋升文档的品质。

如何 Review 文档：

• 业余的视角来保障准确性： 个别由团队里比拟资深的人负责，他们关注的外围点是文档写的对不对，专不业余。如果 Code Review 做的好的话，文档的 Review 也属于 Code Review 的一部分。
• 读者视角保障简洁性： 个别由不相熟这个畛域的人来 Review，比方团队的新人，或者文档的使用者。这部分次要是关注文档是否容易被看懂。
• 写作者视角保障一致性： 由写作经验丰富或者相干畛域比拟资深的人承当，次要是为了保障文档前后是否统一，比方对同一个专业术语的应用和了解是否有歧义。

写文档的哲学

下面局部站在组织和团队的视角来看如何进步文档品质，咱们接下来看看站在集体写作者的视角上如何写出高质量的文档。

5W 法令

5W 法令置信大家曾经听的多了，别离是 Who What When Where Why，这是一个宽泛被用在各行各业的法令，写文档当然也能用（5W 法令堪称万金油，啥中央都能用）。

• WHO： 后面曾经说过了，文档是写给谁看的，读者是谁。
• WHAT： 明确这篇文档的用处，有时候，仅仅阐明文档的用处和目标就能帮你搭建起整个文档的框架。
• WHEN： 明确文档的创立、Review 和更新日期。因为文档也有时效性，明确相干日期能够防止阅读者踩坑。
• WHERE： 文档应该放在哪！倡议一个组织或者团队有对立的永恒文档寄存地址，并且有版本控制。最好是不便查找、应用和分享。
• WHY： 为什么要写这篇文档，你冀望读者读完后从文档中取得什么！

三段式写作

写文章个别都会有三个局部，业余写作者也考究 凤头、猪肚、豹尾 ，这三个词概括出了好文章三局部应有的特点。技术文档也算是文章的一种，所以个别也都会有这三局部，每个局部有其本人的作用，比方 第一局部论述问题，两头局部介绍具体的解决方案，第三局部总结要点。 但这也并不认为着文档应该有三个局部，如果文档内容比拟多，能够将其做更粗疏的拆解，能够适当减少一些冗余的信息帮忙读者了解文档内容。尽管很多工程师都厌恶冗余 竭力谋求简洁，但写文档和写代码不同，适当的冗余反而能够帮忙读者了解，很简略，举个例子，比方写作中常常举例子，举的例子实质上就是冗余信息，活泼的例子必定是能帮忙读者了解形象内容的（我想这就是自举
吧）。

结语

目前看到比拟好的一个景象就是大家越来越器重文档了，但和测试相比 器重的水平还不够。测试曾经是工作流程中不可或缺的一部分了，而文档仍旧还不是。当然这可能和文档自身的个性相干，测试很容易被自动化，也有十分多的主观指标来评估。文档却做不到，首先文档的书写须要人手动染指，而文档的品质也没有太多主观的指标评估，晋升文档的数量和品质只能从文化和工作流程下来逐步扭转。

最初总结下本文几个关键点：

• 随着工夫的推移和组织规模的壮大，文档会越来越重要。
• 文档也应该是开发流程的一部分。
• 一篇文档只专一在一件事上。
• 文档是写给读者看的，而不是给你本人看的。