活文檔：與代碼共同演進

第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
補充知識：顯而易見的文檔（圖靈社區下載）
活文檔模式圖表（圖靈社區下載）