第 1章　重新思考文檔　　1 1.1　一則來(lái)自活文檔世界的故事　1 1.1.1　為什么需要這個(gè)功能　1 1.1.2　明天你就不再需要這個(gè)草圖了　2 1.1.3　抱歉，我們沒(méi)有營(yíng)銷(xiāo)文檔　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　專(zhuān)門(mén)知識(shí)與通用知識(shí)　22 1.8.1　學(xué)習(xí)通用知識(shí)　22 1.8.2　專(zhuān)注于專(zhuān)門(mén)知識(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入門(mén)　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　邊車(chē)文件　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　類(lèi)型驅(qū)動(dòng)文檔　167 8.3.1　從基本類(lèi)型到類(lèi)型　167 8.3.2　被記錄的類(lèi)型和集成的文檔　168 8.3.3　類(lèi)型和關(guān)聯(lián)　168 8.3.4　類(lèi)型優(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　類(lèi)型層次結(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í)的類(lèi)別　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　卡車(chē)系數(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　向管理層推銷(xiāo)活文檔　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ū)下載）