作为团队管理者，经常会接触到人员的交接，所以对技术文档特别重视。但很多技术人自己非常轻视技术文档的书写，然而又时常抱怨文档不完善、质量差、更新不及时……
很多人还是没有写文档的习惯，为什么？主要有以下几点原因：
- 很多工程师习惯将写代码和写作割裂开，不仅仅是在工作上，而且在思想上就认为它们是完全不相关的两项工作，这就导致好多人重代码不重文档。
- 也有很多工程师认为自己不善写作，索性就不写了。
- 大多数人将写文档看做是工作的额外负担。
文档的重要性
高质量的文档对于一个组织或团队来说有非常多的益处，比如让代码和API更容易理解、错误更少；让团队成员更专注于目标；也可以让一些手工操作更容易；另外如果有新成员加入的话有文档也会让他们更快融入……
写文档有比较严重的收益滞后性，不像测试，你跑一个测试case，它能立即告诉你是对还是错，它的价值马上就体现出来了。而写一份文档，随着时间的推移，它的价值才会逐渐体现出来。你可能只写一次文档，将来它会被阅读上百次、上千次，因为一份好的文档可以在未来替你向别人回答类似下面这些问题。
- 为什么当时是这么决策的？
- 为什么代码是这样实现的？
- 这个项目里都有哪些概念？
写文档同样对于写作者也有非常大的好处：
- 帮你构思规范化API：写文档的过程也是你审视你API的过程，写文档时会让你思考你API设计是否合理，考虑是否周全。如果你没法用语言将API描述出来，那么说明你当前的API设计是不合理的。
- 文档也是代码的另一种展现：比如你两年后回过头来看你写过的代码，如果有注释和文档，你可以很快速理解代码。
- 让你的代码看起来更专业：我们都有个感觉，只要文档齐全的API都是设计良好的API，虽然这个感觉并不完全正确，但这两者确实是强相关的，所以在很多人眼里，文档的完善度也成为衡量一个产品专业度的指标。
- 避免被重复的问题打扰：有些问题你只需要写在文档里，这样有人来问你的时候你就可以让他直接去看文档了，而不是又给他解释一遍。
如何产出高质量文档
既然理解了好文档的重要性，我们如何保证在时间的长河中维护好一份文档，可以参考下。
1.像管理代码一样管理文档
对于如何写出好代码，整个技术圈已经有好多经验的总结了，比如书籍《重构》《代码简洁之道》…… 针对各种编程语言，也有相关的规范，比如国外的Google C++规范，国内的阿里Java开发规范等…… 但对于文档 似乎相关的资料却很少。但实际上，不应该把文档和代码割裂开来，你可以简单粗暴地认为文档其实就是用一种特殊语言书写的代码，这种语言就是人类的语言。这么想的话，实际上我们很多在代码和工程中总结出来的经验，也可以直接用在文档中，比如：
- 有统一的规范
- 有版本控制
- 有明确的责任人维护
- 有变更Review机制
- 有问题的反馈和更新机制
- 定期更新
- 有衡量的指标(比如准确性，时效性)
2.清晰的分类
文档大致可以分为以下几种类型，每种类型也有自己不同的特点和写作侧重点。
a.参考文档
参考文档也是大部分开发人员日常会使用和书写的文档，比如我们使用某个框架或者工具，都会有API说明文档，这就属于参考类文档。它并没有太多的要求，只要能向读者展示清楚如何使用即可，但无需向读者讲明具体的实现。
注：参考文档并不仅限于API文档，还包括文件注释、类注释、方法注释，要求都是能准确说明其用法。
b.设计文档
很多公司或者团队在项目开始前都要求有设计文档，设计是项目实施的第一步，所以在设计文档书写的过程中要求尽可能考虑周全，例如该项目的存储、交互、隐私……
好的设计文档应该包含以下几个部分：
设计目标
实现的策略
各种利弊权衡和具体决策
替代方案
各种方案的优缺点
写设计文档的过程也你对整个项目做规划、思考可能出现问题的过程，设计的越详细、思考的越多，未来遇到问题的可能性就会越小。
搜索公众号互联网架构师后台回复“2T”，获取一份惊喜礼包。
c.引导类文档
引导类文档也很常见，一般都是Step by Step的形式。比如我们在使用某个框架或者工具的时候，一般都会有个引导类的文档一步一步帮助你快速上手。大家写引导类文章大家非常容易犯的一个错误就是预设了很多背景知识。一般使用文档都是有开发者写的，他们都非常了解这个工具的相关的知识，所以习惯性的会认为，啊 这个知识点很简单 用户也肯定会吧，实际上用户不一定会。这本质上就是一种认知偏差，这种现象在跨团队协作 尤其是多端协作的时候也非常明显。
这类型的文档写作中，要求写作者尽可能站在用户的视角上思考，极力避免出现和用户的认知偏差，力争每个步骤做到明确无歧义，每两个步骤之间做到紧密衔接。
d.概念性文档
当参考文档无法解释清楚某些东西的时候，就需要概念性文档了，比如某个API的具体实现原理。其主要是为了扩充参考文档，而不是替代参考文档。有时候这和参考文档会有些内容重复，但主要还是为了更深层次的说明某些问题、解释清楚某个概念。
概念性文档也是所有文档中写作最难的，也是被阅读最少的，所以很多情况下工程师最容易忽视。而且还有另外一个问题，没合适的地方放，参考文档可以写代码里，落地页可以写项目主页里，概念性文档似乎也只能在项目文档里找个不起眼的角落存放了。
这类文档的受众会比较广，专家和新手都会去看。另外，它需要强调概念清晰明了，因此可能会牺牲完整性(可以由参考文档补齐)，也有可能会牺牲准确性，这不是说一定要牺牲准确性，只是应当分清主次，不重要的就没必要说了。
e.Landing pages(落地页)
Landing pages就先简单翻译成落地页了，没想到啥恰当的翻译词。比如一个团队或者项目的导航页，虽然没啥具体的内容，但应该包含其他页面的链接。比如你新入职一个团队，比较成熟的团队都会扔给你一个文档，这个文档里包含常用的工具、文档链接，这就是这个团队的落地页。
落地页的问题就是随着时间的推移，页面可能会变的越来越乱，而且有些内容会失效，不过这些问题都好解决，做好定期的维护和整理就行。
落地页的技术难度不高，但要求内容的有效性、完整性和分类清晰。
4.文档Review
在一个组织内，光靠个人去维护文档是不行的，必须得借助群体的智慧。在一个组织内部，文档的变更也应该像代码的变更一样，需要被其他人Review，以提前发现其中的问题并提升文档的质量。
如何Review文档：
专业的视角来保证准确性：一般由团队里比较资深的人负责，他们关注的核心点是文档写的对不对，专不专业。如果Code Review做的好的话，文档的Review也属于Code Review的一部分。
读者视角保证简洁性：一般由不熟悉这个领域的人来Review，比如团队的新人，或者文档的使用者。这部分主要是关注文档是否容易被看懂。
写作者视角保证一致性：由写作经验丰富或者相关领域比较资深的人承担，主要是为了保证文档前后是否一致，比如对同一个专业术语的使用和理解是否有歧义。
写文档的哲学
上面部分站在组织和团队的视角来看如何提高文档质量，我们接下来从个人写作者的视角上如何写出高质量的文档。
写文章一般都会有三个部分，专业写作者也讲究凤头、猪肚、豹尾，这三个词概括出了好文章三部分应有的特点。技术文档也算是文章的一种，所以一般也都会有这三部分，每个部分有其自己的作用，比如第一部分阐述问题，中间部分介绍具体的解决方案，第三部分总结要点。但这也并不以为着文档应该有三个部分，如果文档内容比较多，可以将其做更细致的拆解，可以适当增加一些冗余的信息帮助读者理解文档内容。虽然很多工程师都讨厌冗余 极力追求简洁，但写文档和写代码不同，适当的冗余反而可以帮助读者理解，很简单，举个例子，比如写作中经常举例子，举的例子本质上就是冗余信息，生动的例子肯定是能帮助读者理解抽象内容的（我想这就是自举吧）。
结语
目前看到比较好的一个现象就是大家越来越重视文档了，但和测试相比重视的程度还不够。测试已经是工作流程中不可或缺的一部分了，而文档依旧还不是。当然这可能和文档本身的特性相关，测试很容易被自动化，也有非常多的客观指标来评估。
文档却做不到，首先文档的书写需要人手动介入，而文档的质量也没有太多客观的指标评估，提升文档的数量和质量只能从文化和工作流程上去逐渐改变。
最后总结下本文几个关键点：
- 随着时间的推移和组织规模的壮大，文档会越来越重要。
- 文档也应该是开发流程的一部分。
- 一篇文档只专注在一件事上。