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