活文檔：與代碼共同演進

第 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　活文檔屬于未來？不，是現(xiàn)在　4
1．2　傳統(tǒng)文檔存在的問題　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　協(xié)作　17
1．5．4　有見地　17
1．5．5　螞蟻怎么交換知識：共識主動性　18
1．6　大部分知識是已經(jīng)存在的　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　學(xué)習(xí)通用知識　22
1．8．2　專注于專門知識　23
1．9　確保文檔準(zhǔn)確　23
1．9．1　準(zhǔn)確性機制保證文檔可靠　23
1．9．2　當(dāng)文檔不需要準(zhǔn)確性機制時　25
1．10　挑戰(zhàn)文檔的大問題　25
1．10．1　質(zhì)疑是否真的需要文檔　26
1．10．2　因缺乏信任而需要文檔　26
1．10．3　即時文檔，或者未來知識的廉價選擇　27
1．10．4　質(zhì)疑是否需要傳統(tǒng)文檔　28
1．10．5　減少現(xiàn)在的額外工作　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　當(dāng)活文檔是DDD應(yīng)用時　37
1．13．4　BDD、DDD、XP和活文檔同根而生　37
1．14　小結(jié)　39
第　2章 BDD：活需求說明的示例　40
2．1　BDD是為了對話　40
2．2　實現(xiàn)自動化的BDD是為了活文檔　41
2．3　在文件中解析場景　42
2．3．1　功能文件的意圖　42
2．3．2　功能文件場景　43
2．3．3　需求說明的細節(jié)　43
2．3．4　功能文件中的標(biāo)簽　44
2．3．5　場景即交互式活文檔　45
2．3．6　將場景做成無聊的紙質(zhì)文檔　46
2．4　功能文件示例　46
2．5　用典型案例展示活文檔的方方面面　48
2．6　更進一步：充分利用活文檔　48
2．7　小結(jié)　51
第3章　知識開發(fā)　52
3．1　識別權(quán)威性知識　52
3．2　知識現(xiàn)在在哪里　52
3．3　單一來源發(fā)布　53
3．3．1　制作并發(fā)布文檔的示例　54
3．3．2　發(fā)布一個帶版本號的快照　55
3．3．3　備注　55
3．4　設(shè)置一致性機制　55
3．4．1　運行一致性測試　56
3．4．2　關(guān)于測試假設(shè)的一致性　57
3．4．3　發(fā)布的約定　58
3．5　整合分散的信息　59
3．5．1　如何整合知識　60
3．5．2　實施整合的注意事項　61
3．6　現(xiàn)成的文檔　61
3．6．1　標(biāo)準(zhǔn)詞匯的力量　63
3．6．2　鏈接到標(biāo)準(zhǔn)知識　64
3．6．3　不僅僅是詞匯　64
3．6．4　在會話中使用現(xiàn)成的知識來加速知識傳遞　65
3．7　工具歷史　68
3．8　小結(jié)　69
第4章　知識增強　70
4．1　當(dāng)編程語言不夠用時　70
4．2　使用注解編寫文檔　72
4．2．1　注解不只是標(biāo)簽　73
4．2．2　描述決策背后的依據(jù)　74
4．2．3　嵌入式學(xué)習(xí)　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　元數(shù)據(jù)數(shù)據(jù)庫　80
4．5　設(shè)計自定義注解　81
4．5．1　構(gòu)造型的屬性　81
4．5．2　構(gòu)造型和戰(zhàn)術(shù)模式　82
4．5．3　注解包名稱要有意義　83
4．5．4　強行將標(biāo)準(zhǔn)注解移作他用　83
4．5．5　標(biāo)準(zhǔn)注解：@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　記錄你的決策依據(jù)　90
4．9．1　依據(jù)里有什么　91
4．9．2　使依據(jù)明確　92
4．9．3　超越文檔：被激發(fā)的設(shè)計　92
4．9．4　避免記錄猜測　92
4．9．5　作為預(yù)記錄依據(jù)的技能　93
4．9．6　將依據(jù)記錄作為推動變革的因素　93
4．10　確認你的影響力（又名項目參考文獻）　94
4．11　將提交消息作為全面的文檔　95
4．12　小結(jié)　98
第5章　活知識管理：識別權(quán)威性知識　99
5．1　動態(tài)的知識管理　99
5．1．1　動態(tài)知識管理的示例　100
5．1．2　需要編輯的知識管理　101
5．1．3　不太需要維護的動態(tài)知識管理　101
5．1．4　一庫多用的知識語料庫　102
5．1．5　場景摘要　102
5．2　突出核心　103
5．3　突出啟發(fā)性的范例　104
5．4　導(dǎo)覽和觀光地圖　106
5．4．1　創(chuàng)建觀光地圖　108
5．4．2　創(chuàng)建導(dǎo)覽　109
5．4．3　創(chuàng)建活導(dǎo)覽　111
5．4．4　一個可憐人的文學(xué)式編程　112
5．5　總結(jié)：策展人籌備一場藝術(shù)展覽　113
5．5．1　選擇和整理現(xiàn)有知識　113
5．5．2　在需要時添加缺失的東西　114
5．5．3　使無法到場和以后的人可以訪問　114
5．6　小結(jié)　114
第6章　自動化文檔　115
6．1　活文檔　115
6．1．1　創(chuàng)建活文檔的步驟　115
6．1．2　演示規(guī)則　116
6．2　活詞匯表　116
6．2．1　活詞匯表是如何起作用的　117
6．2．2　請舉個例子吧　117
6．2．3　活文檔的信息管理　119
6．2．4　在限界上下文中創(chuàng)建詞匯表　121
6．3　活圖表　125
6．3．1　用圖表協(xié)助對話　126
6．3．2　一圖一故事　126
6．3．3　活圖表讓你誠實　128
6．3．4　追求完美的圖表　128
6．3．5　渲染活圖表　129
6．3．6　可視化準(zhǔn)則　132
6．3．7　示例：六邊形架構(gòu)的活圖表　136
6．3．8　案例研究：用活圖表呈現(xiàn)業(yè)務(wù)概覽　136
6．3．9　示例：系統(tǒng)上下文圖　142
6．3．10　自動生成設(shè)計文檔所面臨的挑戰(zhàn)　145
6．4　小結(jié)　146
第7章　運行時文檔　147
7．1　示例：活服務(wù)圖表　147
7．1．1　在運行時中增強代碼　148
7．1．2　發(fā)現(xiàn)架構(gòu)　149
7．1．3　讓這項工作起作用的魔法　149
7．1．4　更進一步　149
7．1．5　可見工作方式：工作的軟件即其自身文檔　150
7．2　可見測試　150
7．2．1　特定領(lǐng)域的符號　150
7．2．2　生成自定義的領(lǐng)域特定圖表，從而獲得視覺反饋　152
7．3　示例：使用事件溯源時的可見測試　154
7．3．2　根據(jù)事件溯源場景生成的活圖表　156
7．4　內(nèi)省的工作方式：內(nèi)存中的代碼即知識來源　157
7．4．1　使用反射內(nèi)省　158
7．4．2　不使用反射內(nèi)省　159
7．5　小結(jié)　160
第8章　可重構(gòu)文檔　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　類型驅(qū)動文檔　167
8．3．1　從基本類型到類型　167
8．3．2　被記錄的類型和集成的文檔　168
8．3．3　類型和關(guān)聯(lián)　168
8．3．4　類型優(yōu)于注釋　169
8．4　組合方法　171
8．5　連貫風(fēng)格　172
8．5．1　使用內(nèi)部DSL　172
8．5．2　實現(xiàn)連貫接口　173
8．5．3　連貫風(fēng)格的測試　173
8．5．4　創(chuàng)建一種DSTL　174
8．5．5　何時不應(yīng)使用連貫風(fēng)格　175
8．6　案例研究：由注釋引導(dǎo)的重構(gòu)代碼示例　175
8．7　集成的文檔　176
8．7．1　類型層次結(jié)構(gòu)　177
8．7．2　代碼搜索　177
8．7．3　源自實際用法的語義　177
8．8　使用純文本圖表　178
8．8．1　示例：純文本圖表　178
8．8．2　圖表即代碼　181
8．9　小結(jié)　182
第9章　穩(wěn)定文檔　183
9．1　常青內(nèi)容　183
9．1．1　需求比設(shè)計決策穩(wěn)定　183
9．1．2　高層級目標(biāo)往往很穩(wěn)定　184
9．1．3　很多知識并沒有看起來那么穩(wěn)定　184
9．1．4　案例研究：README文件　184
9．2　關(guān)于常青文檔的提示　187
9．2．1　避免將策略文檔與策略實現(xiàn)文檔混在一起　187
9．2．2　確保穩(wěn)定性　188
9．2．3　使用持久的命名　189
9．2．4　沿著穩(wěn)定軸組織工件　189
9．3　鏈接的知識　190
9．3．1　不穩(wěn)定到穩(wěn)定的依賴關(guān)系　190
9．3．2　斷鏈檢查器　191
9．3．3　鏈接注冊表　191
9．3．4　加書簽的搜索　192
9．4　穩(wěn)定知識的類別　192
9．5　愿景聲明　193
9．5．1　領(lǐng)域愿景聲明　194
9．5．2　目標(biāo)　195
9．5．3　影響地圖　195
9．6　投資穩(wěn)定知識　196
9．6．1　領(lǐng)域浸入　197
9．6．2　調(diào)查墻　197
9．6．3　領(lǐng)域培訓(xùn)　197
9．6．4　“過我的生活”活動　198
9．6．5　影子用戶　198
9．6．6　長期投資　198
9．7　小結(jié)　198
第　10章 避免傳統(tǒng)文檔　199
10．1　關(guān)于正式文檔的對話　200
10．1．1　Wiio溝通定律　201
10．1．2　三個解釋規(guī)則　202
10．1．3　對話的障礙　202
10．2　協(xié)同工作，實現(xiàn)持續(xù)的知識共享　202
10．2．1　結(jié)對編程　203
10．2．2　交叉編程　204
10．2．3　Mob 編程　204
10．2．4　三個（或更多）好朋友　204
10．2．5　事件風(fēng)暴即熟悉產(chǎn)品的過程　205
10．2．6　知識轉(zhuǎn)移會議　205
10．2．7　持續(xù)文檔　205
10．2．8　卡車系數(shù)　206
10．3　在咖啡機旁溝通　206
10．4　想法沉淀　208
10．5　一次性文檔　210
10．6　按需文檔　210
10．6．1　即時文檔　210
10．6．2　盡早激發(fā)即時學(xué)習(xí)　212
10．6．3　驚訝報告　212
10．6．4　包括一些前期文檔　212
10．7　互動式文檔　214
10．8　聲明式自動化　215
10．8．1　聲明式風(fēng)格　216
10．8．2　聲明式依賴關(guān)系管理　216
10．8．3　聲明式配置管理　218
10．8．4　聲明式自動化部署　220
10．8．5　機器文檔　223
10．8．6　關(guān)于普遍自動化的評論　223
10．9　強制性規(guī)范　223
10．9．1　規(guī)則的一些例子　224
10．9．2　不斷發(fā)展規(guī)范　225
10．9．3　強制或鼓勵　226
10．9．4　聲明式規(guī)范　226
10．9．5　工具的問題　227
10．9．6　規(guī)范還是設(shè)計文檔呢　227
10．9．7　如果被篡改，保證標(biāo)簽無效　228
10．9．8　信任至上的文化　229
10．10　受限行為　229
10．10．1　輕松地做正確的事　229
10．10．2　不可能出錯：防錯API　231
10．11　避免編寫文檔的設(shè)計原則　231
10．11．1　可替換性優(yōu)先　231
10．11．2　一致性優(yōu)先　231
10．12　示例：零文檔游戲　232
10．13　小結(jié)　233
第　11章 超越文檔：活設(shè)計　234
11．1　傾聽文檔　234
11．1．1　領(lǐng)域語言怎么了　235
11．1．2　通過巧合設(shè)計編程　235
11．2　謹慎決策　236
11．2．1　“謹慎決策”并不意味著“預(yù)先決策”　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　文檔驅(qū)動開發(fā)　242
11．4．1　文檔讓你誠實　243
11．4．2　文檔驅(qū)動和“避免文檔”之間的明顯矛盾　243
11．5　濫用活文檔（反模式）　244
11．6　活文檔拖延癥　245
11．7　可降解的文檔　245
11．8　干凈透明　246
11．8．1　診斷工具　248
11．8．2　使用正壓清潔內(nèi)部　250
11．9　無處不在的設(shè)計技巧　251
11．10　記者Porter采訪Living Doc Doc先生　251
11．11　小結(jié)　253
第　12章 活架構(gòu)文檔　254
12．1　記錄問題　255
12．2　明確的質(zhì)量屬性　257
12．2．1　利害驅(qū)動的架構(gòu)文檔　257
12．2．2　顯式假設(shè)　258
12．2．3　架構(gòu)簡潔說明架構(gòu)質(zhì)量高　258
12．2．4　持續(xù)發(fā)展：易于更改的文檔　259
12．3　決策日志　259
12．3．1　結(jié)構(gòu)化決策日志的示例　260
12．3．2　用期刊或博客作為腦轉(zhuǎn)儲　263
12．4　分形架構(gòu)文檔　263
12．5　架構(gòu)全景圖　264
12．6　架構(gòu)規(guī)范　266
12．7　透明的架構(gòu)　268
12．7．1　架構(gòu)注解　269
12．7．2　強制性設(shè)計決策　271
12．8　架構(gòu)實現(xiàn)檢查　272
12．9　測試驅(qū)動架構(gòu)　272
12．9．1　質(zhì)量屬性即場景　273
12．9．2　生產(chǎn)環(huán)境中運行時的質(zhì)量屬性　274
12．9．3　其他質(zhì)量屬性　274
12．9．4　從零散的知識到可用的文檔　274
12．10　小規(guī)模模擬即活架構(gòu)文檔　275
12．10．1　小規(guī)模模擬的理想特征　276
12．10．2　簡化系統(tǒng)的技術(shù)　276
12．10．3　構(gòu)建小規(guī)模模擬就有了一半的樂趣　277
12．11　系統(tǒng)隱喻　278
12．11．1　通過談?wù)摿硪粋€系統(tǒng)來解釋這個系統(tǒng)　278
12．11．2　即使沒有先驗知識也很有用　278
12．11．3　隱喻套隱喻　278
12．12　小結(jié)　279
第　13章 在新環(huán)境中引入活文檔　280
13．1　秘密實驗　280
13．2　新事物必須能用而且必須被接受　281
13．2．1　漸漸地開始　281
13．2．2　擴大活文檔項目的范圍并讓人看到　282
13．3　案例研究：向團隊成員介紹活文檔的故事　283
13．3．1　對話優(yōu)先　283
13．3．2　第 一次匯報　284
13．3．3　是時候討論代碼了　284
13．3．4　決策日志和導(dǎo)覽　285
13．4　針對活文檔的普遍反對意見　286
13．4．1　注解并不是用來編寫文檔的　286
13．4．2　“我們已經(jīng)在做了”　286
13．5　將遺留文檔遷移到活文檔中　287
13．6　邊際文檔　287
13．7　案例研究：在批處理系統(tǒng)中引入活文檔　288
13．7．1　README文件和現(xiàn)成的文檔　288
13．7．2　業(yè)務(wù)行為　289
13．7．3　顯露式運行和單一信息源　289
13．7．4　供開發(fā)人員使用的集成文檔和供其他干系人使用的活詞匯表　289
13．7．5　展示設(shè)計意圖的活圖表　290
13．7．6　聯(lián)系信息和導(dǎo)覽　290
13．7．7　微服務(wù)總圖　290
13．8　向管理層推銷活文檔　291
13．8．1　從實際問題出發(fā)　291
13．8．2　活文檔計劃　292
13．8．3　對比當(dāng)前的狀況與承諾的更美好的世界——實現(xiàn)人們的愿望　293
13．9　在精神實質(zhì)上合規(guī)　295
13．9．1　案例研究：遵守ITIL合規(guī)性要求　296
13．9．2　ITIL示例　296
13．10　小結(jié)　297
第　14章 為遺留應(yīng)用程序編寫文檔　298
14．1　文檔破產(chǎn)　298
14．2　遺留應(yīng)用程序就是知識化石　298
14．3　氣泡上下文　300
14．4　疊加結(jié)構(gòu)　302
14．5　突出結(jié)構(gòu)　303
14．6　外部注解　305
14．7　可降解的轉(zhuǎn)化　305
14．7．1　示例：絞殺者應(yīng)用程序　305
14．7．2　示例：破產(chǎn)　306
14．8　商定標(biāo)語　306
14．9　強制執(zhí)行的遺留規(guī)則　307
14．10　小結(jié)　308
補充知識：顯而易見的文檔（圖靈社區(qū)下載）
活文檔模式圖表（圖靈社區(qū)下載）