活文档 与代码共同演进 (法)西里尔·马特雷尔 著 黄晓丹 译 专业科技 文轩网

第1章重新思考文档1
1.1一则来自活文档世界的故事1
1.1.1为什么需要这个功能1
1.1.2明天你就不再需要这个草图了2
1.1.3抱歉，我们没有营销文档2
1.1.4你一直在用这个词，但并非其本意3
1.1.5给我看看完整的图，你就知道哪里有问题了3
1.1.6活文档属于未来？不，是现在4
1.2传统文档存在的问题4
1.2.1编写文档通常不太酷4
1.2.2文档的缺陷5
1.2.3敏捷宣言与文档9
1.2.4是时候开启文档2.0了9
1.3文档编写的是知识10
1.3.1知识的来源11
1.3.2知识如何演进11
1.3.3为什么需要知识11
1.4文档是为了传递知识14
1.5活文档的核心原则15
1.5.1可靠16
1.5.2省力16
1.5.3协作17
1.5.4有见地17
1.5.5蚂蚁怎么交换知识：共识主动性18
1.6大部分知识是已经存在的18
1.7固有文档19
1.7.1固有文档与外部文档20
1.7.2固有文档与外部文档示例20
1.7.3优选固有文档21
1.7.4就地文档21
1.7.5机器可读的文档22
1.8专门知识与通用知识22
1.8.1学习通用知识22
1.8.2专注于专门知识23
1.9确保文档准确23
1.9.1准确性机制保证文档可靠23
1.9.2当文档不需要准确性机制时25
1.10挑战文档的大问题25
1.10.1质疑是否真的需要文档26
1.10.2因缺乏信任而需要文档26
1.10.3即时文档，或者未来知识的廉价选择27
1.10.4质疑是否需要传统文档28
1.10.5减少现在的额外工作29
1.10.6减少以后的额外工作29
1.11让活动变得有趣30
1.12文档重启31
1.12.1活文档：非常简短的版本35
1.12.2更好的文档编制方法35
1.13DDD入门36
1.13.1DDD概述36
1.13.2活文档和DDD36
1.13.3当活文档是DDD应用时37
1.13.4BDD、DDD、XP和活文档同根而生37
1.14小结39
第2章BDD：活需求说明的示例40
2.1BDD是为了对话40
2.2实现自动化的BDD是为了活文档41
2.3在文件中解析场景42
2.3.1功能文件的意图42
2.3.2功能文件场景43
2.3.3需求说明的细节43
2.3.4功能文件中的标签44
2.3.5场景即交互式活文档45
2.3.6将场景做成无聊的纸质文档46
2.4功能文件示例46
2.5用典型案例展示活文档的方方面面48
2.6更进一步：充分利用活文档48
2.7小结51
第3章知识开发52
3.1识别权威性知识52
3.2知识现在在哪里52
3.3单一来源发布53
3.3.1制作并发布文档的示例54
3.3.2发布一个带版本号的快照55
3.3.3备注55
3.4设置一致性机制55
3.4.1运行一致性测试56
3.4.2关于测试假设的一致性57
3.4.3发布的约定58
3.5整合分散的信息59
3.5.1如何整合知识60
3.5.2实施整合的注意事项61
3.6现成的文档61
3.6.1标准词汇的力量63
3.6.2链接到标准知识64
3.6.3不仅仅是词汇64
3.6.4在会话中使用现成的知识来加速知识传递65
3.7工具历史68
3.8小结69
第4章知识增强70
4.1当编程语言不够用时70
4.2使用注解编写文档72
4.2.1注解不只是标签73
4.2.2描述决策背后的依据74
4.2.3嵌入式学习74
4.3按照约定编写文档77
4.3.1使用约定的遗留代码中的活文档78
4.3.2记录约定78
4.3.3始终遵守约定79
4.3.4约定的局限性79
4.4外部文档编写方法80
4.4.1边车文件80
4.4.2元数据数据库80
4.5设计自定义注解81
4.5.1构造型的属性81
4.5.2构造型和战术模式82
4.5.3注解包名称要有意义83
4.5.4强行将标准注解移作他用83
4.5.5标准注解：@Aspect和面向切面编程84
4.5.6默认注解或除非必要85
4.6处理全模块知识85
4.6.1处理多种模块86
4.6.2在实践中进行全模块增强86
4.7固有知识增强87
4.8机器可访问的文档88
4.9记录你的决策依据90
4.9.1依据里有什么91
4.9.2使依据明确92
4.9.3超越文档：被激发的设计92
4.9.4避免记录猜测92
4.9.5作为预记录依据的技能93
4.9.6将依据记录作为推动变革的因素93
4.10确认你的影响力（又名项目参考文献）94
4.11将提交消息作为全面的文档95
4.12小结98
第5章活知识管理：识别权威性知识99
5.1动态的知识管理99
5.1.1动态知识管理的示例100
5.1.2需要编辑的知识管理101
5.1.3不太需要维护的动态知识管理101
5.1.4一库多用的知识语料库102
5.1.5场景摘要102
5.2突出核心103
5.3突出启发性的范例104
5.4导览和观光地图106
5.4.1创建观光地图108
5.4.2创建导览109
5.4.3创建活导览111
5.4.4一个可怜人的文学式编程112
5.5总结：策展人筹备一场艺术展览113
5.5.1选择和整理现有知识113
5.5.2在需要时添加缺失的东西114
5.5.3使无法到场和以后的人可以访问114
5.6小结114
第6章自动化文档115
6.1活文档115
6.1.1创建活文档的步骤115
6.1.2演示规则116
6.2活词汇表116
6.2.1活词汇表是如何起作用的117
6.2.2请举个例子吧117
6.2.3活文档的信息管理119
6.2.4在限界上下文中创建词汇表121
6.3活图表125
6.3.1用图表协助对话126
6.3.2一图一故事126
6.3.3活图表让你诚实128
6.3.4追求完美的图表128
6.3.5渲染活图表129
6.3.6可视化准则132
6.3.7示例：六边形架构的活图表136
6.3.8案例研究：用活图表呈现业务概览136
6.3.9示例：系统上下文图142
6.3.10自动生成设计文档所面临的挑战145
6.4小结146
第7章运行时文档147
7.1示例：活服务图表147
7.1.1在运行时中增强代码148
7.1.2发现架构149
7.1.3让这项工作起作用的魔法149
7.1.4更进一步149
7.1.5可见工作方式：工作的软件即其自身文档150
7.2可见测试150
7.2.1特定领域的符号150
7.2.2生成自定义的领域特定图表，从而获得视觉反馈152
7.3示例：使用事件溯源时的可见测试154
7.3.2根据事件溯源场景生成的活图表156
7.4内省的工作方式：内存中的代码即知识来源157
7.4.1使用反射内省158
7.4.2不使用反射内省159
7.5小结160
第8章可重构文档161
8.1代码即文档161
8.1.1文本布局162
8.1.2编码约定164
8.2命名作为最初的文档165
8.2.1组合方法：你需要为它们命名166
8.2.2惯用命名受上下文影响166
8.2.3依靠框架编码166
8.3类型驱动文档167
8.3.1从基本类型到类型167
8.3.2被记录的类型和集成的文档168
8.3.3类型和关联168
8.3.4类型优于注释169
8.4组合方法171
8.5连贯风格172
8.5.1使用内部DSL172
8.5.2实现连贯接口173
8.5.3连贯风格的测试173
8.5.4创建一种DSTL174
8.5.5何时不应使用连贯风格175
8.6案例研究：由注释引导的重构代码示例175
8.7集成的文档176
8.7.1类型层次结构177
8.7.2代码搜索177
8.7.3源自实际用法的语义177
8.8使用纯文本图表178
8.8.1示例：纯文本图表178
8.8.2图表即代码181
8.9小结182
第9章稳定文档183
9.1常青内容183
9.1.1需求比设计决策稳定183
9.1.2高层级目标往往很稳定184
9.1.3很多知识并没有看起来那么稳定184
9.1.4案例研究：README文件184
9.2关于常青文档的提示187
9.2.1避免将策略文档与策略实现文档混在一起187
9.2.2确保稳定性188
9.2.3使用持久的命名189
9.2.4沿着稳定轴组织工件189
9.3链接的知识190
9.3.1不稳定到稳定的依赖关系190
9.3.2断链检查器191
9.3.3链接注册表191
9.3.4加书签的搜索192
9.4稳定知识的类别192
9.5愿景声明193
9.5.1领域愿景声明194
9.5.2目标195
9.5.3影响地图195
9.6投资稳定知识196
9.6.1领域浸入197
9.6.2调查墙197
9.6.3领域培训197
9.6.4“过我的生活”活动198
9.6.5影子用户198
9.6.6长期投资198
9.7小结198
第10章避免传统文档199
10.1关于正式文档的对话200
10.1.1Wiio沟通定律201
10.1.2三个解释规则202
10.1.3对话的障碍202
10.2协同工作，实现持续的知识共享202
10.2.1结对编程203
10.2.2交叉编程204
10.2.3Mob编程204
10.2.4三个（或更多）好朋友204
10.2.5事件风暴即熟悉产品的过程205
10.2.6知识转移会议205
10.2.7持续文档205
10.2.8卡车系数206
10.3在咖啡机旁沟通206
10.4想法沉淀208
10.5一次性文档210
10.6按需文档210
10.6.1即时文档210
10.6.2尽早激发即时学习212
10.6.3惊讶报告212
10.6.4包括一些前期文档212
10.7互动式文档214
10.8声明式自动化215
10.8.1声明式风格216
10.8.2声明式依赖关系管理216
10.8.3声明式配置管理218
10.8.4声明式自动化部署220
10.8.5机器文档223
10.8.6关于普遍自动化的评论223
10.9强制性规范223
10.9.1规则的一些例子224
10.9.2不断发展规范225
10.9.3强制或鼓励226
10.9.4声明式规范226
10.9.5工具的问题227
10.9.6规范还是设计文档呢227
10.9.7如果被篡改，保证标签无效228
10.9.8信任至上的文化229
10.10受限行为229
10.10.1轻松地做正确的事229
10.10.2不可能出错：防错API231
10.11避免编写文档的设计原则231
10.11.1可替换性优先231
10.11.2一致性优先231
10.12示例：零文档游戏232
10.13小结233
第11章超越文档：活设计234
11.1倾听文档234
11.1.1领域语言怎么了235
11.1.2通过巧合设计编程235
11.2谨慎决策236
11.2.1“谨慎决策”并不意味着“预先决策”238
11.2.2文档是一种代码审查方式239
11.3丢脸的文档239
11.3.1示例：丢脸的文档240
11.3.2故障排除指南240
11.3.3丢脸的代码文档241
11.3.4记录错误还是避免错误242
11.4文档驱动开发242
11.4.1文档让你诚实243
11.4.2文档驱动和“避免文档”之间的明显矛盾243
11.5滥用活文档（反模式）244
11.6活文档拖延症245
11.7可降解的文档245
11.8干净透明246
11.8.1诊断工具248
11.8.2使用正压清洁内部250
11.9无处不在的设计技巧251
11.10记者Porter采访LivingDocDoc先生251
11.11小结253
第12章活架构文档254
12.1记录问题255
12.2明确的质量属性257
12.2.1利害驱动的架构文档257
12.2.2显式假设258
12.2.3架构简洁说明架构质量高258
12.2.4持续发展：易于更改的文档259
12.3决策日志259
12.3.1结构化决策日志的示例260
12.3.2用期刊或博客作为脑转储263
12.4分形架构文档263
12.5架构全景图264
12.6架构规范266
12.7透明的架构268
12.7.1架构注解269
12.7.2强制性设计决策271
12.8架构实现检查272
12.9测试驱动架构272
12.9.1质量属性即场景273
12.9.2生产环境中运行时的质量属性274
12.9.3其他质量属性274
12.9.4从零散的知识到可用的文档274
12.10小规模模拟即活架构文档275
12.10.1小规模模拟的理想特征276
12.10.2简化系统的技术276
12.10.3构建小规模模拟就有了一半的乐趣277
12.11系统隐喻278
12.11.1通过谈论另一个系统来解释这个系统278
12.11.2即使没有先验知识也很有用278
12.11.3隐喻套隐喻278
12.12小结279
第13章在新环境中引入活文档280
13.1秘密实验280
13.2新事物必须能用而且必须被接受281
13.2.1渐渐地开始281
13.2.2扩大活文档项目的范围并让人看到282
13.3案例研究：向团队成员介绍活文档的故事283
13.3.1对话优先283
13.3.2第一次汇报284
13.3.3是时候讨论代码了284
13.3.4决策日志和导览285
13.4针对活文档的普遍反对意见286
13.4.1注解并不是用来编写文档的286
13.4.2“我们已经在做了”286
13.5将遗留文档迁移到活文档中287
13.6边际文档287
13.7案例研究：在批处理系统中引入活文档288
13.7.1README文件和现成的文档288
13.7.2业务行为289
13.7.3显露式运行和单一信息源289
13.7.4供开发人员使用的集成文档和供其他干系人使用的活词汇表289
13.7.5展示设计意图的活图表290
13.7.6联系信息和导览290
13.7.7微服务总图290
13.8向管理层推销活文档291
13.8.1从实际问题出发291
13.8.2活文档计划292
13.8.3对比当前的状况与承诺的更美好的世界——实现人们的愿望293
13.9在精神实质上合规295
13.9.1案例研究：遵守ITIL合规性要求296
13.9.2ITIL示例296
13.10小结297
第14章为遗留应用程序编写文档298
14.1文档破产298
14.2遗留应用程序就是知识化石298
14.3气泡上下文300
14.4叠加结构302
14.5突出结构303
14.6外部注解305
14.7可降解的转化305
14.7.1示例：绞杀者应用程序305
14.7.2示例：破产306
14.8商定标语306
14.9强制执行的遗留规则307
14.10小结308
补充知识：显而易见的文档（图灵社区下载）
活文档模式图表（图灵社区下载）