活文檔 與代碼共同演進 Living Documentation: Continuous Knowledge Sharing by Design

西里爾·馬特雷爾（Cyrille Martraire）

Arolla公司CTO、聯合創始人，Paris Software Crafters協會創始人，經常在國際性會議上發表演講。西里爾稱自己為開發者，自1999年起他就在為初創公司、軟件供應商和各大企業設計軟件了。他曾領導過多個重大項目，在處理大型遺留系統方面經驗豐富。他對軟件設計的各個方面都充滿熱情，特別是TDD、BDD和DDD。

第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．13 DDD入門36
1．13．1 DDD概述36
1．13．2活文檔和DDD 36
1．13．3當活文檔是DDD應用時37
1． 13．4 BDD、DDD、XP和活文檔同根而生37
1．14小結39

第2章BDD：活需求說明的示例40
2．1 BDD是為了對話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使用內部DSL 172
8．5．2實現連貫接口173
8．5．3連貫風格的測試173
8．5．4創建一種DSTL 174
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．1 Wiio溝通定律201
10．1．2三個解釋規則202
10．1．3對話的障礙202
10．2協同工作，實現持續的知識共享202
10．2．1結對編程203
10．2 ．2交叉編程204
10．2．3 Mob編程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不可能出錯：防錯API 231
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採訪Living Doc Doc先生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． 1 README文件和現成的文檔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．2 ITIL示例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

補充知識：顯而易見的文檔（圖靈社區下載）
活文檔模式圖表（圖靈社區下載）