1.书籍信息

封面
书名	《活文档：与代码共同演进》
作者	西里尔·马特雷尔
状态	已读完
简介	这是一本活文档参考指南，教你如何像写代码一样有趣地持续维护文档。书中系统地阐述了计算机软件开发各个阶段中文档写作的步骤、内容、方法、工具、特点和要求，详尽指导软件开发人员和文档开发工程师写出规范的文档，包括软件文档的概念和内容，软件文档编写的原则和步骤，软件文档的管理和维护，可行性研究报告、软件需求报告、软件测试计划等文档的写作方法和写作技巧。
资源
评价（满6颗	活文档的理念不错，对软件开发过程中的文档分析的不错，但是具体到落地的例子感觉不深入 当理念看还可以 ⭐⭐⭐

2.书摘

活文档：与代码共同演进
西里尔·马特雷尔
11个笔记
1.2 传统文档存在的问题

uml 不受欢迎什么依据？草率了吧
迷恋符号 我们发现UML符号现在越来越不受欢迎了。UML在1997年被采用为标准，并在之后的十年里成为所有软件的通用符号，尽管它并不适用于所有情况。从那时起，再也没有其他符号被广泛地使用，而且即使不太合适，世界各地的团队仍会用一些UML符号来记录内容。当你只知道UML时，每一个图表看起来都像是它的标准图集之一。
1.3 文档编写的是知识

知识缺失会导致两种后果。浪费时间：这些时间本可以更好地投入到其他方面的改进上。次优决策：从长远来看，其他决策可能更有意义或成本更低。
1.5 活文档的核心原则

现代软件开发的本质是群体性智慧和嵌在代码库中的标记。通过让程序员的注意力更可靠地集中在与需要完成的工作最相关的事情上，标记使共识主动性的效率更高。
1.12 文档重启

超越文档感觉翻译的很别扭啊
超越文档：最后，我们来讨论超越文档领域，在这里我们可以质疑一切，并认识到文档这个概念在转移和存储知识之外还能带来很多好处。我们因此获得启发，并且以一种更具批判性的方式重新考虑其他所有方法和技术。活文档的这一方面更为抽象，但很重要
2.7 小结

总结一句话：将需求与代码放到一起，并且按照特定的语法叙述，通过工具在构建时自动验证需求与代码是否一致，并自动生成文档（可以是在线的，也可以是特定格式）
BDD是活文档的典型示例，主要依靠团队成员之间的频繁对话。这是构建软件的必要工作的直接组成部分，但是它以业务人员和开发人员都能访问的形式保留了在项目中收集的知识。尽管它会在代码和场景中重复知识，但随附的工具仍可确保所有信息保持同步。然而，BDD仅处理了软件的业务行为。在后续章节中，我们将探讨如何将这些想法外推到与软件开发相关的其他活动中。
3.8 小结

一句话总结：从哪找到你的知识？ 从权威的知识产生地方找，从那里做一手的发布
3.8 小结 大多数（但不是全部）有价值的知识已经以某种形式存在于你的系统工件中。只有承认各种权威性知识来源的存在，你才能开始活文档实践。要开始实践，还需要确定是否有单一信息源（可以将它提取出来，生成不同形式的文档），或者是否存在冗余信息源（它们需要一致性机制）。如果知识分散在多个位置，那么你可能需要一种整合机制将其归为一条知识。
4.8 机器可访问的文档

声明每个被禁止或可接受的包对包的依赖关系是很烦琐的，但是请想象一下在各个类之间这样做：这让人望而却步！但是，如果类已经做了标记（例如@ValueObject、@Entity或@DomainService），则依赖关系检查器可以强制执行你喜欢的依赖关系限制。例如，我喜欢执行以下规则。值对象应仅依赖于其他值对象。实体绝不能将任何服务实例作为成员字段。
4.12 小结

你需要增强系统代码从而使知识完整。在这种增强代码的方法中，注解、约定和其他技术有助于记录最重要的知识。增强代码的过程也为你提供了一个将技能以嵌入式学习方式传播给同事的机会。
6.3 活图表

并借助Google Guava ClassPath方便地扫描了整个类路径。我自己的实用工具库DotDiagram是基于Graphviz DOT语法的一个简便的包装类，用于创建.dot文件，然后由Graphviz DOT语法进行神奇的自动布局和渲染。[插图]
13.1 秘密实验

是一个很好的开始
如果你觉得只有自己一个人对活文档感兴趣，可能希望悄悄地、渐渐地开始制作活文档，不会让很多人知道。最重要的是，这样不需要获得授权。这是因为无论采取什么方法，编写文档都是专业开发人员日常工作的一部分。 因此，自然而然地将活文档一点点引入日常工作，成为工作的一部分。在确定设计决策、意图和依据时就开始对它们做注解。如果有一些闲暇时间或真正需要文档，请将分配的时间用于创建简单的文档自动化，例如简单的活图表或基本词汇表。尽量使文档保持简单，使其在几个小时或更短的时间内就能发挥作用。不要把它说成一场革命，而是只把它当作一种高效做事的天然方式。强调这种方法能带来的收益，而不只是本书提供的理论。 当然，当其他人对这种方法产生兴趣后，你可以将活文档作为一个主题进行讨论，并向他们推荐本书。

3.读后感 & 点评

认为一般
活文档的理念不错，对软件开发过程中的文档分析的不错，但是具体到落地的例子感觉不深入 当理念看还可以
微信读书

活文档
涉及到自动检查程序
新的需求描述语法
推进起来不容易

| 关于写到代码中的文档描述

写到代码中的文档描述有个问题

我只能看到当前项目的

跨项目，不在一个存储库，是有问题的
是零零散散的

| 扫描代码自动生成文档

开源？
自研？

4.相关资料

基于活文档理念的 UI 自动化测试框架 - 掘金
https://juejin.cn/post/7007321145812713479

代码解析器 https://zhuanlan.zhihu.com/p/115606527 可以作为生成活文档的一个组件