1.
從 Living Documentation
看見
資訊管理與開發囧境
Ean

2.
在軟體開發大洋中漂流的小小竹筏，持續關注各
種架構與技術的發展，但最近年逐漸關注軟體本
身的業務價值。
- DDD 社群志工
- 後端工程師
Ean

3.
撰寫 / 維護文件是 Loading
開發的囧境
開發文件是過期的 !!
資訊文件要放在那?

4.
- 文件的本質
- 知識的使用、增強與展示
- 業務需求與文件的結合
- 文件的同步
- 程式即文件
Domain-Driven Design
Behavior-Driven Development
Clean Code
Clean Architecture
Agile
knowledge management

5.
https://agilemanifesto.org/iso/zhcht/manifesto.html
敏捷宣言
個人與互動 流程與工具>
可用的軟體 詳盡的文件>
與客戶合作 合約協商>
回應變化 遵循計劃>

6.
敏捷宣言
擁抱文件，但不為從不維護與罕用的文件浪費時
間與精力
個人與互動 流程與工具>
可用的軟體 >
與客戶合作 合約協商>
回應變化 遵循計劃>
詳盡的文件

7.
文件的本質與目的
轉移有價值的知識，給不同時空的其他
人(受眾)。
空間
時
間
- 值得記錄的長期利益
- 值得記錄的大量人群的利益
- 有價值或重要的知識
文件 知識

8.
文件 知識
觀察
對話
實驗
知識的建立與形成
通用
專屬 有價值，並且搜尋不到。

9.
文件
知識
1. 忘記前面決策與其脈絡
2. 擁有知識的人離去
3. 新成員的加入
缺少知識付出的成本
1. 浪費時間
2. 次佳的決策
依據知識做決定，然後建立更多的知識。
解決的問題、做出的決策、決策方式、決策根據、考
慮過的替代方案。
軟體開發與設計 開發持續時間長

10.
1. 無法存取
2. 巨量
3. 破碎
4. 隱含
5. 不可復原
6. 未寫下
軟體專案 大部份知識己經存在於系統之中 。
瓶頸
文件
知識
1. 直接給實作技術，表示知識。
2. 不易遺失，並與最新版本一致。
3. 無法立即展現給非開發者。
內部
1. 與實作技術無關。(傳統文件)
2. 不限工具。
3. 容易遺失，且文件與 產品最新版本有落差。
外部

11.
敏捷宣言
擁抱文件，但不為從不維護與罕用的文件浪費時
間與精力
缺少文件傳統
變成同事與客戶的
困擾與麻煩
個人與互動 流程與工具>
可用的軟體 >
與客戶合作 合約協商>
回應變化 遵循計劃>
詳盡的文件
文件製作
轉移有價值的知識，
給現在與未來的其他
人。(轉換與擴散)
專注於重點
● 是否需要？
● 受眾是誰？
● 需要立即產出嗎?

12.
傳統文件的產生方式
活動分離 想到什麼寫什麼
抄錄 → 重複的知識 → 浪
費時間
美化圖表 資訊墳場
記號法的兩極化
(執迷 vs 沒有)
誤導 (過時文件) 還有其他重要的事

13.
敏捷宣言
實用、持續更新、低成本的文件製作方式
測試驅動開發 TDD
行為驅動開發 BDD
領域驅動開發 DDD
持續交付
個人與互動 流程與工具>
可用的軟體 >
與客戶合作 合約協商>
回應變化 遵循計劃>
詳盡的文件
缺少文件傳統
變成同事與客戶的
困擾與麻煩
Document 2.0
文件製作
擁抱文件，但不為從不維護與罕用的文件浪費時
間與精力
專職人員負責手動同步文件，是一種反模式的
不建議作法。

14.
低投入
1. 簡單化。
2. 標準重於自定方案。 (採用人盡皆
知)
3. 長青內容。(不常變動)
4. 重構知識。
5. 內部文件。
洞察力
1. 清楚的決策。
2. 內含學習。
3. 事實檢查。
合作
1. 對話重於正規文件。
2. 可存取的知識。
3. 共同負責。
可靠性
1. 利用可用的知識。
2. 正確性機制。(確保同步)
Live Document
四大原則

15.
知識
展示
利用 增強

16.
展示
增強利用
知識

17.
展示
增強利用 現成的文件
大部份的知識己經記錄在某個 產業文獻中。
● 查詢知識來源或詢問有知識的人。
● 盡可能採用標準實作與標準術語。
查詢知識來源的好處
1. 參考其他來源
2. 可能有改善建議，或是沒有考慮的替代方案
3. 可能更深入說明狀況，提升洞察。
4. 檢驗方法是否合理。若找不到佐證，要注意。
5. 學習其他人如何討論這個狀況。
標準術語
標準知識
加速知識轉移
使用現成的知識
有效率的溝通與查詢

18.
展示
增強利用 權威知識
1
4
5
3
2

19.
展示
增強利用 文件發佈
自動化機制 發佈的文件
發佈快照
視為不可變且不應修改
版本編號
有明確的版本與最新版位置的連
結。
權威知識
單一來源
多個來源
調和機制 (查證機制)
自動化整合所有分散的知識碎片。

20.
文件只有在有機制確保正確性時，才可信
任。
● 有發佈機制的單一來源
● 有傳播機制的冗餘來源
● 有調解機制的冗餘來源
文件無需正確性確保機制的情況。
● 單一用途
● 過去的記錄
展示
增強利用 文件的正確性

21.
展示
利用 增強
知識

22.
增強程式碼 = 程式碼 + 注釋
1. 使用程式碼能以結構化的方式說出完整的故事。
定義宣告每個決定背後的 意圖與理由。
2. 盡可能增強後的知識，放在靠近相關程式碼的地方。
3. 使用結構化的注釋， 說明設計與其目的，清楚了解當時決策背後的理由。
4. 依循慣例。如命名法，記錄寫法，以及限制。
5. 設計自定注釋。
展示
利用 增強
Attribute Annotation
JavaC#

23.
記錄理由
以某程文件的形式，記錄每一個重要決策的理由，包括背景、主要替代方案。
- 若無法將其正規化記錄，決策本身可能不如所需的謹慎。
決策選擇背後的理由
- 當時背景
- 選擇背後的問題或需求
- 決策本身而非所選擇的方案，以及理由
- 認真考慮過的主要替代方案、 沒有選擇它的原因或不同背景會選擇它的原
因。
展示
利用 增強
動機設計
- 表示什麼東西有
待改進的信號
記錄方式
- 現寫的文件
- 注釋
- 部落格文章

24.
已提交說明為詳細文件
仔細撰寫的提交說明，對好幾種目的很有價 值，是另一種高產出活動:
- 思考: 思考完成的工作
- 說明: 明確展現意圖
- 報表
● 指定修改類型
● 說明修改範圍
展示
利用 增強

25.
利用 增強
展示
知識

26.
動態整理展示
增強利用
展示
將己經存在的知識，轉換為有意義與有用的東西。轉換
突顯核心
突顯啟發樣版
需專注的特定部份，在主要模型庫中，標註核心領域。 (Core Domain)
要推廣的風格或最佳實作的高品質程式碼範例 。(必需維護與適時的重構)
- 實際使用的程式碼
- 由團隊一起決定，找出幾個一致同意的範本。再突過特殊注釋突顯。
從大集合之中，選取有關的部份，以建立 說出故事的一致性敘
事

27.
增強利用
展示
導覽與景點圖
景點圖: 想要強調的最重要的地方，數量建議 5~7 個，最多不超過 10 個。
導覽: 程式碼的線性排序。 (說故事)

28.
增強利用
展示
總結
- 選擇與安排現有的知識
- 有需要時補漏
- 缺席者與後人的可存取性
好的文件，以新知識增加價值，用不同視角強調關係。
空間
時
間轉移有價值的知識，給不同時
空的其他人(受眾)。
文件的本質與目的

29.
Living documentation

30.
https://martinfowler.com/bliki/BoundedContext.html
活詞彙表
統一語言
詞彙表
● 領域的通用語言
● 依據 Bounded
Context 建立各自的詞
彙表
● 需要維護
統一語言
詞彙表

31.
你的文件是否能順利表達業務行為?
運用領域語言
專注在更高階的目的，並使用情
境的具體範例。
reference: https://en.wikipedia.org/wiki/Roberval_balance
使用 BDD 情境描述應用程式的
行為。
程式原始碼 描述應用程式的行
為。
使用 BDD 情境描述應用程
式的行為。
程式原始碼 描述應用程式
的行為。
冗餘 調和
行為驅動開發(Behavior-driven development, BDD)

32.
使用 Gherkin 語法，依不同目的，進行各情境的規格細節的描述。而這些情境可視為 Live
Document。
1. 合作
2. 低投入
3. 調和機制產生的可靠性
4. 富有洞察力
5. 針對目標受眾
符合 Live Document 核心精神
Feature: Guess the word
# The first example has two steps
Scenario: Maker starts a game
When the Maker starts a game
Then the Maker waits for a Breaker to join
# The second example has three steps
Scenario: Breaker joins a game
Given the Maker has started a game with the
word "silky"
When the Breaker joins the Maker's game
Then the Breaker must guess a word with
5 characters
Gherkin Syntax
Garkin

33.
Specflow + LivingDoc

34.
有些問題很難用文說明，但很容易用圖說明。
1. 當圖表長期有效，應設定自動化機制，自動 產生圖表。(持續整合)
2. 一圖一故事，每個圖表只有一個目的。刪除多餘的資訊
活圖表
使用 Graphviz 自動產生
視覺化指南
1. 由左到右，由上而下軸有意義
2. 讓佈局有意義
3. 讓大小與顏色有意義
https://graphviz.org/
使用 PlantUML 自動產生

35.
期望產生的圖表Alistair Cockburn 網站的六角架構
由 Source Code
產生的圖表
● 依需求的與使用頻率來決定圖
表的建立方式
● 簡單、小量調整的圖表，可用程
式碼自動產生方式
● 專門而複雜的圖表，需使用專用
的工具，額外處理
活圖表

36.
程式碼即文件
1. 用正確的詞彙進行命名。
- 需要一致與共享內涵
- 基於上下文的命名
- 有助搜尋
2. 型別驅動
- 盡可使用強型別，避免使用原始型別與基本集合。
- 型別重於註解
static void Main(string[] args)
{
// int amount = 12000; // EUR
Money amount = Money.inEUR(12000);
}

37.
程式碼即文件
3. 組合方法
- 主要方法為高易讀性的高抽象層，而非實作
- 次方法為實作的低抽象層。
4. 流暢的風格
- 模擬自然語法，如 Linq
- 但並非全然適用，因地適宜。e.g. API
public Position equivalentPosition(Trade[]
trades)
{
if (hasNo(trades))
{
return positionZero();
}
return new
Position(quantityOfFirst(trades));
}
private bool hasNo(Trade[] trades)
{
return trades.Length == 0;
}
private Position positionZero()
{
return new Position(0);
}
private static double quantityOfFirst(Trade[]
trades)
{
return trades[0].getQuantity();
}

38.
穩定的文件(長青文件)
投資穩定的知識 - 業務領域知識
版本陳述
領域願景的陳述
目標
避免混合策略文件與實作文件
使用長壽的命名
連結知識
依知識生命週期的分類
偏向簡短、沒有太多的細節
專注於 High-Level 知識 — 整體局勢
專注於目標與意圖，而非實作決策
較校於技術，更專注於業務概念
特質 方法
定位 領域

39.
分享知識的方針
分享知識的最好方式是交談
合作持續分享知識-> 確保將最重要的知識保存在某處
- 結對程式設計
- 事件風暴
- 領域敘事
- 知識轉移會議
想法沉澱
- 人少時，用交談、草圖等，可採用快速、簡單的知識交換方式
- 有用、重要、所有人都應該知道的，採用重量級的文件制作

40.
設計與架構
深思熟慮的決策
- 目標是什麼?
- 有什麼選項?
- 知道什麼?
- 期待什麼?
好的設計
- 對稱
- 高階的抽象概念
- 一致性
- 可替代性與封裝
深思熟慮設計 ≠ 事先設計
除了解決方案外，並專注於問題的討
論與記錄。
確保問題的基本知識有良好的記錄，
並確保每個人都知道。
1. 專案內的利益關係，像業務領域
挑戰、技術考量、UI/UX、其他系
統整合。
2. 重要架構的決策日記。記綠了決
策、理由、考慮過的主要替代方
案、主要後果。
3. 透明的架構。

41.
推薦的相關資訊
● https://martinfowler.com/

42.
Q&A