活文檔：與代碼共同演進(jìn)

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