活文档：与代码共同演进 —— 摘录

• 让知识容易获取

  要将知识从技术人员的大脑传递到非技术人员的大脑，需要将知识变得更易于获取。使知识变得易于获取的另一种情况是使其能被有效地搜索到。—— 1.4 文档是为了传递知识

• 更喜欢固有文档

  存储文档的最佳位置是被记录的事物本身。—— 1.7 固有文档

• 单一来源发布

  每一项知识都只放在一个地方，使其成为权威性知识来源。当文档受众无法直接访问这些知识，而你又必须为他们提供这些知识时，请从该单一知识来源发布文件。不要通过复制和粘贴的方法将知识元素包含到要发布的文档中，而是使用自动化机制直接从单一的权威性知识来源创建需要发布的文档。—— 3.3 单一来源发布

• 嵌入式学习

  在代码中加入更多知识不仅仅是为了编写文档，还能有意识地帮助提高团队工作的技能。在制定你的增强代码策略时，请给它一个机会。代码增强时，想想当你的同事发现这段代码时会做何反应。—— 4.2.3 嵌入式学习

• 记录决策依据

  如果你能马上告诉我你的意图和背景信息，那么只要我是一个熟练的专业人员，我就可能会做出与你相同的决策。但是，如果没有意图和背景信息，你就会想知道 “他们当时在想什么”。—— 4.9 记录你的决策依据

• 将依据记录作为推动变更的因素

  如果你做得一个变更引发了一个被遗忘的问题，而你没有看到这个问题是因为它没有被记录在案，那么可能会在无意中造成伤害。—— 4.9.6 将依据记录作为推动变更的因素

• 将提交信息作为全面的文档

  精心编写的提交信息使每一行代码都有据可查。将文件提交到源代码控制系统中时，添加包含提交信息的有意义的注释是良好实践。人们经常会忽略这个操作，结果就是还要浪费时间打开文件来查找更改的内容。—— 4.11 将提交信息作为全面的文档

• 为代码提供指引

  熟悉代码库的过程可能类似于熟悉城市的过程，然而代码库比大多数城市变化得更快。因此，必须为代码库提供指引，以保证后期只需要做最少的工作就能使其保持最新。—— 5.4 导览和观光地图

• 活文档

  活文档是根据权威性来源的最新知识自动生成的文档。—— 8. 可重构文档

• 依靠框架编码

  当你使用诸如 Spring Boot 之类的的现成框架时，你的代码必须符合框架的要求。你写出来的代码不会太出乎人意料，而且当你熟悉了框架后，就可以理解大多数代码，从知识转移的角度来说这是一件好事。—— 8.2.3 依靠框架编码

• 不稳定到稳定的依赖关系

  引用稳定的内容不会产生很高的成本，因为这种依赖关系不会经常改变，所以不会产生太多影响。反过来，如果引用的是不稳定内容，那么只要依赖关系发生变化，你就必须一直更改。这个理念同时适用于代码和文档。—— 9.3.1 不稳定到稳定的依赖关系

• 投资稳定知识

  稳定知识是一项可以长期收益的投资。学习一个主题是一项昂贵的投资。学习那些过个几年就要更新的技术，我觉得很难。业务领域知识和软件架构的基础知识是常青内容，特别值得学习。—— 9.6 投资稳定知识

• 在白板上进行对话

  人们在白板前一起工作和交谈是最有效的沟通方式，而纸上的交流则是最无效的沟通方式。在大多数情况下，要实现有效的知识共享，最好是通过简单的交谈、提问和回答来完成，而不是通过书面文档。—— 10.1 关于正式文档的对话

• 文档是一种代码审查方式

  文档使产品和开发过程更加透明。因此，文档也是一个有用的反馈工具，可以帮你在应用程序的整个生命周期中进行调整和更正。—— 11.2.2 文档是一种代码审查方式

• 向上管理

  软件开发领域有一个很大的问题，就是管理预算并做出最大决策的人员根本看不到软件的内部质量。这种对内部质量意识的缺失会阻碍这些人做出明智的决定。如果开发人员能够让非技术人员感性地理解代码的内部质量，他们会变得更有说服力。管理层常常会质疑开发人员的意见。相比之下，管理层更能接受工具的输出，因为工具是中立且客观的（或者至少他们认为是这样的）。—— 11.8.2 使用正压清洁内部

• 我们需要文档

  虽然没有明确的文档我们也能活，任何人都可以上手一个未知的系统并让它正常运行。但是让它工作是一个很低的门槛，而让它工作可能需要很长时间。文档可以加快交付速度，因为他可以缩短你重建系统思维模型的时间。另一个作用是尝试记录系统相关的知识是了解系统不正确之处的好办法。—— 我们真的需要文档

• 从成本考虑

  编写文档是进行测试和编写源代码等昂贵成本之前的低成本手段（PS：原话我找不到了，看到的朋友麻烦留个言，我重新去找一下）