本文大部分内容翻译总结自第10章_Documentation_。另外，本书的电子版近期可以免费下载https://abseil.io/resources/swe_at_google.2.pdf，感兴趣的同学可以下载阅读。首先申明，本题中提到的文档不限于纯文本文档，还包括代码注释（注释也是文档的一种特殊形式）。很多技术人员本身就鄙视写技术文档，但他们却经常抱怨文档不全、质量差、更新不及时……这种程序员之间普遍存在的矛盾甚至演变成笑话。文档的重要性高质量的文档对组织或团队有很多好处，例如使代码和API更易于理解并减少错误；让团队成员更专注于目标；并且让一些手工操作变得更容易；另外，如果有新成员加入，有文档会帮助他们更快地集成...写文档有严重的收入滞后，不像测试，你跑一个测试用例，它可以立即告诉你是否是对与错，它的价值立马体现出来。而写一篇文档，随着时间的推移，它的价值也会逐渐体现出来。你可能只写了一次文档，以后就会被阅读成百上千次，因为一个好的文档可以在以后为你解答类似下面这样的问题。为什么做出这样的决定？为什么代码是这样实现的？这个项目中的概念是什么？……写文档对写手也有很大的好处：帮助你构思标准化的API：写文档的过程也是检验你的API的过程。写文档会让你思考你的API设计是否合理和周到。如果你不能用语言描述你的API，那么你现在的API设计是不合理的。文档也是代码的另一种表现形式：比如两年后回头看自己写的代码，如果有注释和文档，可以很快看懂代码。让你的代码看起来更专业：我们都有一种感觉，只要API文档齐全，它就是一个设计良好的API。虽然这种感觉并不完全正确，但两者确实有很强的相关性，所以在很多人看来这里，文档的完备性也成为了衡量一个产品专业性的指标。避免被重复的问题打扰：有些问题只需要写在文档中，这样当有人来找你问你的时候，你可以让他直接去看文档，而不用再给他解释一遍。为什么大多数人不喜欢写文档？关于文档的重要性，每个技术人员或多或少都知道，但是很多人还是没有写文档的习惯，为什么呢？除了上面提到的文档收入滞后之外，还有几个原因：很多工程师习惯于把写代码和写代码分开，不仅在工作上，而且还认为他们是完全不相关的两份工作，这导致很多人重新记录代码。也有很多工程师认为自己写的不好，干脆就不写了。这其实是偷懒的借口。写文件不需要华丽的辞藻，不需要生动的语言，只需要把问题说清楚。有时候工具使用不当也会影响文档的编写。如果没有将编写文档嵌入到开发工作流程中的良好编写工具，编写确实会增加工作量。大多数人将编写文档视为工作的额外负担。没时间写代码，哪有时间写文档！，这其实是一个错误的概念。文档虽然前期有投入，但是后期可以大大降低你代码的维护成本。如何制作高质量的文档既然我们明白了好的文档的重要性，那如何才能保证一份文档在时间的长河中得到很好的维护呢？这里有一些相关的方法供大家参考。像代码管理一样管理文档对于如何写出好的代码，整个技术圈已经总结了很多经验，比如书籍《重构》《代码简洁之道》...对于各种编程语言，也有相关的规范，比如GoogleC++规范国外的，国内的阿里巴巴Java开发规范等等。。。但是文档的相关资料好像很少。但实际上，文档和代码是不应该分开的。你可以简单粗略地认为，文档其实就是用一种特殊的语言写成的代码，也就是人类的语言。这样想的话，其实很多我们在代码和工程上总结出来的经验，也可以直接用在文档上，比如：有统一的规范，版本控制，明确责任人维护，变更Review机制、有问题的反馈和更新机制会定期更新可衡量的指标（例如准确性、及时性）以明确您的读者是谁。写文档有一个很常见的错误，就是很多人写文档都是为了自己。在这种情况下，它会导致你的文档只能被你自己或者具有类似知识背景的人看懂。这个问题在团队小的时候没问题。你们都在做类似的工作，所以你们可以看懂文档。但当团队逐渐壮大后，问题就会凸显出来。新人有时候和你的工作背景不一样，甚至现在做的工作内容也不一样。这时候他们就很难看懂你之前写的文档了。所以在写文档之前，请明确你的文档可能的读者会是哪些人，然后根据他们的特点，着重考虑如何让他们理解。当然，文档不一定要严肃和完美，只要它能向你的潜在读者解释问题即可。记住文档是写给别人看的，不是给自己看的。按照专业水平，读者大致可以分为三种类型：新手、老手和专家。为不同层次的人写作需要一个重点。比如对于新手，需要重点关注所涉及的术语和概念，然后详细讲解具体的实现。相反，对于专家，您可以省略此额外信息。注意这里没有严格的标准，因为有些文章新手和高手都会看，这里还是需要具体分析。读者分类的另一种方法是根据阅读文档的目的进行分类。例如，如果有人知道他们遇到了什么问题，他们就会来寻找解决方案。还有一群人，只有简单的想法，不知道具体的问题。例如，以读取数据库慢为例。前者已经知道数据库慢可能是因为数据量太大，没有建立索引。后者可能会关注为什么读数据库慢。这时候，你可能需要引入额外的数据库相关的原理。分类明确的文献大致可以分为以下几种类型，每种类型也有自己不同的特点和写作重点。参考文档参考文档也是大多数开发人员日常使用和编写的文档。比如我们在使用某个框架或者工具的时候，都会有API文档，就是一个参考文档。它没有太多的要求，只要能清楚地向读者展示如何使用即可，但不需要向读者解释具体的实现。注意：参考文档不仅限于API文档，还包括文件注解、类注解、方法注解，都需要准确描述其用法。设计文档许多公司或团队在项目开始前都需要设计文档。设计是项目实施的第一步，因此在编写设计文档的过程中需要尽可能多地考虑项目的存储、交互、隐私……一份好的设计文档应该包括以下内容parts:实现设计目标的策略各种利弊权衡和具体的决策备选方案各种备选方案的优缺点编写设计文档的过程也是规划整个项目和思考可能出现的问题的过程，更多详细的设计和更多的思考，你以后遇到问题的可能性就越小。指导文件指导文件也很常见，一般都是StepbyStep的形式。比如我们在使用某个框架或者工具的时候，通常会有一个引导文档，一步一步的帮助你快速上手。当我们写介绍性文章时，我们最常犯的错误之一就是预设了很多背景知识。通常，使用文档是由开发人员编写的。他们都非常了解这个工具的相关知识，所以他们习惯性的认为，啊，这个知识点很简单，用户肯定会。事实上，用户不一定知道。这本质上是一种认知偏差，这种现象在跨团队协作，尤其是多终端协作中也非常明显。在这类文档的编写中，要求作者尽可能站在用户的角度思考问题，尽量避免与用户的认知偏差，力求每一步都清晰明了，做到紧密衔接每两步。概念性文档当参考文档无法解释清楚某件事时，就需要概念性文档，比如某个API的具体实现原理。它主要是为了扩充参考文档，而不是取代它。有时与参考文档重复这一点，但主要是为了更深层次地解释某些问题并清楚地解释某个概念。概念文档也是所有文档中最难写的，也是阅读最少的，所以很多时候工程师最容易忽略它们。而且还有一个问题，就是没有合适的地方放。参考文档可以写在代码里，着陆页可以写在项目首页。概念文档似乎只能存放在项目文档的一个不起眼的角落。此类文件将有更广泛的受众，专家和新手都会阅读。另外需要强调的是，概念清晰清晰，所以可能会牺牲完整性（可以参考文档来完成），也可能会牺牲准确性。这并不是说必须牺牲准确性，而是要区分轻重缓急。不用说了。Landingpages（着陆页）Landingpages简单的先翻译成landingpages，没想到有什么合适的翻译词。例如，一个团队或项目的导航页面，虽然没有具体的内容，但应该包含其他页面的链接。比如你刚加入一个团队，比较成熟的团队会丢给你一个文档，里面有常用的工具和文档链接，这就是团队的登陆页面。着陆页的问题在于，随着时间的推移，页面可能会变得越来越乱，有些内容会失效，但这些问题很容易解决，只要做好定期的维护和整理即可。着陆页的技术难度不高，但要求内容的有效性、完整性和分类清晰。文件审查在一个组织中，单靠个人来维护文件是不够的，必须依靠集体的智慧。在一个组织内部，文档的更改应该像代码更改一样由其他人审查，以便提前发现问题并提高文档质量。如何审稿：专业视角，确保准确：一般都是团队资深人士负责。他们关心的核心点是文档写得对不对，专业不专业。如果CodeReview做得好，文档的Review也是CodeReview的一部分。读者的视角确保简单：一般不熟悉这个领域的人会审阅，比如团队的新人，或者文档的用户。这部分主要看文档是否通俗易懂。作者角度保证一致性：由有丰富写作经验的人或相关领域比较资深的人来承担，主要是保证文档的一致性，比如在使用和理解上是否有歧义同一个专业术语。以上部分文档写作的哲学是从组织和团队的角度讲如何提高文档的质量。下面我们就从写手个人的角度来看如何写出高质量的文档。5W法则相信大家对5W法则已经耳闻颇多了。TheyareWhoWhatWhenWhereWhy，这是各行各业广泛使用的规则。使用）。WHO：前面说了，文档是为谁写的，谁是读者。内容：阐明本文件的目的。有时候，仅仅解释文档的目的和目的，就可以帮助你构建整个文档的框架。WHEN：指定文件的创建、审查和更新日期。因为文件也是时效性的，明确相关日期可以防止读者步入陷阱。WHERE：文档应该放在哪里！建议组织或团队有统一的永久文件存放地址和版本控制。最好易于查找、使用和共享。WHY：你为什么要写这篇文档，你希望读者阅读后从文档中得到什么！三段式写作文章一般分为三个部分。专业作家也关注凤头、五花肉和豹尾。这三个词概括了一篇好文章应该具备的特点，分为三个部分。技术文档也是文章的一种，所以一般分为三部分。每个部分都有自己的作用。比如第一部分说明问题，中间部分介绍具体解决方案，第三部分总结要点。但这并不意味着文件应该分为三个部分。如果文档内容较多，可以拆解得更详细一些，可以增加一些冗余信息，帮助读者理解文档内容。虽然很多工程师讨厌冗余，力求简单，但是写文档和写代码是不一样的。适当的冗余可以帮助读者理解。这很简单。例如，示例通常以书面形式给出。对于其余的信息，生动的例子肯定会帮助读者理解抽象的内容（我认为这是bootstrapping）。结语目前我看到的一个比较好的现象就是大家越来越重视文档，但是和测试相比，重视的程度还不够。测试已经是工作流程不可或缺的一部分，而文档还不是。当然，这可能与文档本身的特性有关。测试可以很容易地自动化，并且有很多客观的指标可以评估。但是，文件不能做。首先，文档的编写需要人工干预，评价文档质量的客观指标不多。提高文档的数量和质量只能从文化和工作流程上逐步改变。最后，我总结一下本文的要点：随着时间的推移和组织规模的增长，文档将变得越来越重要。文档也应该是开发过程的一部分。一份文件只关注一件事。文档是为读者编写的，而不是为您自己编写的。
