具體描述
這是一本活文檔參考指南，教你如何像寫代碼一樣有趣地持續維護文檔。
書中係統地闡述瞭計算機軟件開發各個階段中文檔寫作的步驟、內容、方法、工具、特點和要求，詳盡指導軟件開發人員和文檔開發工程師寫齣規範的文檔，包括軟件文檔的概念和內容，軟件文檔編寫的原則和步驟，軟件文檔的管理和維護，可行性研究報告、軟件需求報告、軟件測試計劃等文檔的寫作方法和寫作技巧。
好的，這是一份關於《活文檔：與代碼共同演進》的圖書簡介，內容詳實，旨在勾勒齣本書的核心價值與作者的獨特視角，同時避免提及任何AI相關的內容，力求展現齣專業、深入的技術解讀風格。 --- 《活文檔：與代碼共同演進》圖書簡介 在軟件開發的復雜迷宮中，文檔曾是那個被遺忘的角落，一個靜態的、容易過時的負擔。然而，當代碼的演進速度超越瞭文檔的更新速度時，我們麵對的不再是“文檔缺失”，而是“誤導性文檔”的巨大風險。本書《活文檔：與代碼共同演進》正是在這樣的背景下應運而生，它不是一本傳統意義上的文檔編寫指南，而是一份關於軟件生命周期管理和知識傳承的革命性思考。 本書深入探討瞭一種全新的文檔範式——“活文檔”。活文檔的核心理念在於，文檔不應是開發完成後的附加物，而是代碼本身不可分割的一部分，與代碼的每一次修改、每一次重構、每一次部署同步呼吸、共同演進。我們摒棄瞭“一次性文檔”的謬論，轉而擁抱一個持續集成、持續反饋的知識生態係統。 第一部分：重塑認知——為何我們需要“活文檔”？ 我們從軟件行業中普遍存在的“文檔債務”現象切入。通過大量的案例分析，我們揭示瞭傳統文檔模式的弊端：維護成本高昂、信息滯後導緻決策失誤、新成員入職的知識鴻溝等。接著，本書係統地闡述瞭“活文檔”的哲學基礎。它不僅僅是技術上的改進，更是對軟件開發文化、團隊協作方式的深刻變革。我們探討瞭如何將文檔的價值與軟件的價值對齊，確保文檔的準確性成為一種“副作用”，而非額外的“開銷”。 第二部分：構建基石——工具、技術與流程的集成 活文檔的實現需要堅實的技術支撐。本書詳細介紹瞭如何將文檔生成、存儲和展示過程無縫集成到現有的開發工作流中。我們不會拘泥於某一種特定的技術棧，而是提供一套通用的架構思路。 代碼即文檔（Code as Documentation）： 探討如何利用類型係統、清晰的命名規範、高精度的注釋和結構化代碼注釋（如Docstrings、XML Comments）來承載第一層級的“活文檔”。這層文檔是機器可讀、最貼近事實的。 文檔即測試（Documentation as Tests）： 介紹如何將關鍵的係統行為描述轉化為可執行的測試用例，例如使用行為驅動開發（BDD）的敘事結構來描述用戶故事和係統契約。這確保瞭描述係統的行為與實際執行的行為始終保持一緻。 自動化生成與發布： 深入研究現代文檔生成工具（如Sphinx, MkDocs, Doxygen的現代化替代品）如何與CI/CD流水綫深度集成。本書強調瞭“文檔構建”應成為軟件構建過程中的一個標準步驟，任何代碼提交都必須伴隨著文檔的更新驗證。 第三部分：超越代碼——知識的架構化與可視化 活文檔的價值遠不止於代碼層麵的注釋。本書將重點放在更高層次的係統設計文檔、架構決策記錄（ADR）以及領域知識的沉澱。 架構決策記錄（ADR）的實踐： 我們將ADR視為活文檔的重要組成部分，並展示如何將其格式化、版本化，並與對應的代碼庫保持同步。每當一個重大設計決策被采納或修改時，相應的文檔也應被視為代碼一樣進行“提交”和“審查”。 領域模型的可視化： 如何利用代碼模型（如UML、C4模型）的自動化生成能力，來可視化復雜的領域結構。這些可視化圖錶不再是靜態的PowerPoint文件，而是可以通過代碼驅動、實時更新的“活視圖”。 用戶導嚮的知識地圖： 針對不同的受眾（開發者、運維人員、産品經理），如何構建多維度的文檔視圖。活文檔的靈活性允許我們為同一套底層知識提供定製化的呈現方式，確保每個人都能接收到最相關、最易於理解的信息。 第四部分：文化變革——培養持續進化的團隊 技術工具隻是實現活文檔的手段，真正的核心在於團隊文化的轉變。本書鼓勵讀者建立“文檔即責任”的文化。 代碼審查中的文檔環節： 提齣將文檔的準確性、清晰度納入代碼審查（Code Review）的標準環節，確保新的知識點在被閤並前就已經被記錄和驗證。 反饋循環的建立： 討論如何設計高效的文檔反饋機製，讓閱讀者（無論是內部團隊還是外部用戶）能夠輕鬆地指齣文檔中的過時或模糊之處，並將這些反饋直接轉化為待辦任務。 知識的沉澱與傳承： 活文檔係統如何降低知識流失的風險，確保核心經驗和設計意圖能夠穩定地傳遞給下一代維護者。 結語 《活文檔：與代碼共同演進》是一本獻給所有追求軟件卓越的工程師、架構師和技術管理者的指南。它挑戰瞭我們對文檔的傳統理解，指明瞭一條更可持續、更可靠的知識管理路徑。閱讀本書，你將學會如何將文檔從開發的“次要産物”提升為“核心資産”，讓你的知識體係與你的代碼庫一樣，充滿活力、永不陳舊。這不僅僅是關於如何寫文檔，更是關於如何構建一個自我記錄、自我優化的軟件係統。 ---
作者簡介
西裏爾·馬特雷爾（Cyrille Martraire）
Arolla公司CTO、聯閤創始人，Paris Software Crafters協會創始人，經常在國際性會議上發錶演講。西裏爾稱自己為開發者，自1999年起他就在為初創公司、軟件供應商和各大企業設計軟件瞭。他曾領導過多個重大項目，在處理大型遺留係統方麵經驗豐富。他對軟件設計的各個方麵都充滿熱情，特彆是TDD、BDD和DDD。
目錄資訊
第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
補充知識：顯而易見的文檔（圖靈社區下載）
活文檔模式圖錶（圖靈社區下載）
· · · · · · (收起)
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
補充知識：顯而易見的文檔（圖靈社區下載）
活文檔模式圖錶（圖靈社區下載）
· · · · · · (收起)
讀後感
評分
評分
評分
評分
評分
用戶評價
评分
很多技術書籍要麼過於學術化，要麼過於偏重某一門具體的語言工具。我期待《活文檔：與代碼共同演進》能提供一種跨越技術棧的通用理念。如果它僅僅是介紹如何用Markdown配閤某個靜態站點生成器來寫文檔，那意義就不大瞭。我更希望它探討的是思維模式的轉變：如何將撰寫文檔視為編寫代碼的一部分，如何量化文檔的“健康度”或“新鮮度”。這種思維的轉變，纔是真正實現“活”文檔的關鍵。我需要的是一套能夠被任何技術團隊采納和實施的、關於知識沉澱和傳遞的哲學，而不是一套針對特定工具的速成手冊。這本書能否提供這種宏觀的視角和實踐的深度結閤，將是我判斷其價值高低的重要標準。
评分閱讀完這本書的概要後，我腦海中立即浮現齣無數次修改文檔的痛苦經曆——代碼改動瞭，文檔裏還在引用舊的API或者錯誤的配置路徑，結果不是用戶抱怨，就是新加入的同事無所適從。這本書似乎瞄準瞭現代軟件工程中的一個痛點：文檔的“死期”總是比我們預想的要早。如果它能提供一套切實可行的方法論，讓文檔的更新與代碼的提交、閤並流程無縫集成，那將是革命性的。我關注的重點在於其實現細節，它究竟是通過某種自動化工具鏈，還是更深層次的語言層麵的支持來實現這種“活”的狀態？一個真正能與代碼同呼吸的文檔，應該能讓我們在閱讀代碼時，就能同時獲取到最準確的上下文信息，這纔是高效協作的基石。
评分我對於這本書中可能觸及的“演進”層麵尤其感興趣。軟件的生命周期中，重構是常態，而文檔往往是重構時最先被遺忘的犧牲品。如果文檔能夠像代碼一樣進行版本控製、進行Review，甚至能被Merge Conflict機製所約束，那該是多麼理想的狀態。這本書的標題暗示瞭這種動態性，我猜測它會深入討論如何將文檔視為一種“代碼資産”來管理，而不是純粹的“內容資産”。這可能涉及到文檔的元數據管理、依賴追蹤，甚至是文檔的測試策略。如果能夠提供一種機製，確保文檔的有效性（Validity）與代碼的可執行性（Executability）同步，那麼這本書的理論價值將遠遠超齣普通的技術手冊範疇。
评分這本書的齣版，對我這種常年浸淫在各種技術文檔和代碼庫之間的“老油條”來說，無疑是一個及時的提醒。我們太習慣於把文檔和代碼看作是兩個獨立的實體，文檔是寫給用戶的說明書，代碼是執行任務的機器。然而，當我們麵對一個復雜係統，或者一個需要多人協作維護的項目時，這種割裂帶來的維護成本和認知負擔是難以估量的。這本書似乎在探討的，正是如何打破這種壁壘，讓文檔不再是僵死的、滯後於代碼的附屬品，而是成為代碼本身演進過程中不可分割的一部分。我非常期待看到作者如何構建一個理論框架，讓我們能夠真正意義上實現“文檔與代碼共舞”，而不是“文檔在代碼身後蹣跚”。這不僅關乎編寫規範，更關乎一種全新的軟件開發哲學。
评分對於初入行的新人來說，理解一個龐大代碼庫的邏輯結構常常像在迷宮裏摸索。那些冗長、晦澀的README文件往往隻是一個開始，真正的知識隱藏在注釋和設計決策的“潛颱詞”裏。這本書如果能深入探討如何讓文檔“主動”地嚮讀者展示這些隱性知識，那價值就太大瞭。想象一下，如果代碼塊本身就能攜帶解釋性的注釋，並且這些注釋能夠被工具提取並組織成易於導航的指南，豈不是能極大地降低新成員的學習麯綫？我希望看到書中能有具體的案例，展示如何設計這樣的“活文檔”結構，使其既能服務於快速參考，又能支持深層次的架構探索，避免信息過載。
评分粗略翻瞭一下，主要關注其中一些思想性的東西，有一說一，很個人的角度來說，實用性不算很強，部分原則值得注意。
评分很nice
评分本書的價值在於強調瞭文檔的重要性，在缺少文檔的情況下，團隊根本無法提高生産力。
评分很nice
评分這本書已經翻瞭個大概，但是仍然沒有找到打動我的那部分；甚至我都沒有get到書的整體脈絡和架構。文檔/知識傳遞應該是不錯的主題，但是好像並沒有講好；或者譯者傳遞有誤，很多句子感覺很生硬
相關圖書
本站所有內容均為互聯網搜索引擎提供的公開搜索信息，本站不存儲任何數據與內容，任何內容與數據均與本站無關，如有需要請聯繫相關搜索引擎包括但不限於百度，google,bing,sogou 等
© 2026 onlinetoolsland.com All Rights Reserved. 本本书屋 版权所有