doc-refine — 技術文件閱讀體驗優化指南
審閱與改寫邊界
先區分審閱和改寫：只要求審閱時提供問題與建議；已明確要求修改時，只改授權文件。涉及行為或事實變化而非表達調整時，保留原意並指出需要確認的部分。
精簡前保護：技術行為、API/資料契約、前提與邊界條件、安全及法律警告、無障礙替代說明、有效範例、來源連結和穩定錨點。程式碼裡已有同樣行為，不足以證明文件可以刪除；局部必要重複可以幫助獨立閱讀。
兩個檢查目標
所有判斷最終歸約為兩個問題：
| 公理 | 問自己的問題 | 一句話 |
|---|---|---|
| ① 快速找到 | 目標讀者能從目錄與標題判斷資訊在哪嗎？ | 路標清晰 |
| ② 每段有用處 | 刪掉後是否損失完成任務、理解行為或控制風險所需的資訊？ | 資訊完整且精練 |
對每一段內容執行這兩個校驗。不滿足 ① → 改標題/加圖表/調結構。 不滿足 ② → 核對保護項與讀者任務，再建議合併或精簡；不以篇幅為由刪除必要內容。
工作流
1. 診斷（先讀全文，不急著改）
通讀目標文件，逐 section 記錄問題：
- 標題能否脫離編號獨立傳達內容？（不→公理 ① 違反）
- 同一邏輯/規則在 2+ 處出現？（是→公理 ② 違反）
- 這段行為說明是否幫助使用者理解契約、限制或結果？先判斷用途，不按「是什麼/為什麼」機械刪除。
- 引導語是否只有重複鋪墊？可精簡措辭，但保留其中的步驟定位、警告或限制。
- 3+ 項對比散落在散文裡？（是→該用表格）
- 圖是否比文字更容易理解流程或狀態？按目標渲染器能力選 Mermaid 或保留文字。
- 範例是否解決真實疑問、錯誤恢復或邊界情況？保留對目標讀者有效的範例。
2. 修復（按公理分類施加）
具體規則見下方 §公理 ① 和 §公理 ②。
3. 校驗（量化基準）
修復後按需讀取 校驗清單，檢查資訊完整性與閱讀效果。 不是每個數字都必須達標——它們是診斷工具而非法律，清晰優先時可破例。
公理 ①：快速找到
標題辨識度
標題是路標。維護者掃 TOC 時應該一眼知道每個 section 裝了什麼。
判斷標準：如果你需要點進 section 才知道它講什麼，標題太泛了。
| ❌ 太泛 | ✅ 可辨識 | 為什麼改 |
|---|---|---|
5.1 表級 | 5.1 專案 CRUD（表級端點） | 「表級」可以是任何東西 |
5.3 行級 | 5.3 行級協作端點 | 讀者知道這裡有認領/交付等操作 |
5.4 匯出 | 5.4 全量 CSV 匯出 | 什麼格式？全量還是部分？ |
端點 | HTTP 端點 | 消除歧義 |
技巧：核心概念太短時，加括號限定詞補充關鍵資訊。但別過度—— 目標是 ≤15 個字傳達「這節有什麼」，不是寫論文標題。
資訊架構
- 一節一職：以教學、操作、參考或解釋的主要讀者任務組織內容；需要的 API 簽章或簡短背景可以保留，長篇資料用交叉連結。
- 核心在前，細節在後：最重要的資訊放在 section 開頭或文件頂部 （Progressive Disclosure）。進階/邊緣資訊可以摺疊或放附錄。
- 自足原則：維護者從任何一頁開始讀都不需要「前序知識」 （Every Page is Page One）。需要前置概念時，在 section 頂部宣告並加連結。
圖表替代文字
當關係、順序或對比用圖更清楚時再用圖；保留可檢索文字與必要的替代說明。
決策樹：
資訊類型是？
├─ 多步驟流程 / 有分支判斷 → 流程圖（flowchart）
├─ 事件驅動的狀態變化 → 狀態圖（stateDiagram-v2）
├─ 3+ 項 × 2+ 維度對比 → 表格
├─ 元件關係 / 架構層級 → 示意圖 + 分層
├─ 定義 / 上下文 / 精確數值 → 文字（預設）
└─ 不確定 → 預設文字（圖是錦上添花非裝飾）
Mermaid 最佳實踐：
- 節點 ≤30——超出後佈局演算法不可讀，拆「概覽→細節」多圖
- 為分支條件和含義不清的關係加標籤；清楚的順序箭頭可不標，避免標籤噪音
- 用
subgraph分組相關節點 TD（自上而下）適合層級；LR（從左到右）適合序列/管線
表格設計（Tufte 原則）：
- 刪除不必要的線、底紋、純裝飾——「Above all else show the data」
- 最小有效差異：視覺區分盡可能微妙但清晰
- 數字按列對齊便於掃描比較
- 文字始終水平，禁止垂直排列
公理 ②：每段有用處
消重
同一資訊出現在多處是可維護性的頭號敵人——改了一處忘了另一處。
檢測標準（命中任一條 → 需要消重）：
- 同一段邏輯/規則在 2+ section 出現 → 留權威源（通常是資料模型或狀態機節），其餘改交叉引用
- 核對行為、前提、風險與獨立閱讀後，確無資訊損失的段落 → 合併或精簡
- 文件重複實作細節 → 判斷讀者是否需要；保留行為說明與契約，不以程式碼已有為刪除理由
- 多種等價做法 → 給出預設建議；保留相容性、權限或使用條件不同的必要替代
ARID ≠ DRY：文件接受必要的重複——教學裡重述參考節的概念是合理的。 但消除平行維護：同一個事實不能在兩處獨立維護，否則必有一處過時。
精簡
砍掉一切不為讀者當前需求的內容。
| 壞味道 | 修法 | 為什麼 |
|---|---|---|
| 重複鋪墊：「在本節中我們將討論…」 | 合併為直接表述 | 保留必要的步驟定位 |
| 填充詞：「需要注意的是」 / 「值得一提的是」 | 精簡引導語 | 警告或限制本身仍須保留 |
| 被動語態連篇（「被用於…」「將會被…」） | 改主動 SVO | 更短、更清晰、讀者知道「誰在做什麼」 |
| 同義詞漂移（同一功能用不同詞） | 統一術語，一詞一義 | 讓讀者明確同一功能的名稱 |
| 難讀的長嵌套句 | 按邏輯拆句 | 不拆散條件、例外與結論的關係 |
| 列舉等價方案 | 推薦方案在前，必要替代隨後 | 保留不同約束下的可行選擇 |
範例克制
範例是最強的速答工具，也是最容易被濫用的內容類型。 Write the Docs 特意寫 「Include (some) examples」——括號裡的 「some」 是刻意的限定。
該用範例的時機：
- 讀者需要快速答案，會直接跳到範例（很多人的第一反應）
- 概念沒有具體例子就難以理解
- 示範的是高頻、真實的用例
不該用範例的時機：
- 在示範顯而易見的東西（Microsoft: 「Don't illustrate obvious points」）
- 無助理解的人為場景；清楚標記且能驗證行為的合成範例可以保留
- 僅為「完整性」而加，沒有使用者真實需求驅動
- 範例已經夠多了——再加會降低可掃描性
好範例：
- 只覆蓋最常見用例，不窮舉
- 自包含且可執行（複製貼上就能工作）
- 從簡單到複雜遞進
- 展示預期輸出讓讀者驗證
- 僅在範例仍可執行或已明確前提時省略樣板；保留必要 import、錯誤處理與預期輸出
壞範例：
- 示範顯而易見的東西
- 不真實的人造場景
- 一個範例試圖涵蓋太多變數
- 塞入與範例無關的例外處理
- 未驗證卻聲稱可執行的程式碼；無法執行時明確標註驗證限制
位置規則：
- 簡單的一行範例 → 內嵌在正文中
- 較長的範例 → 與密集參考資料分離（獨立段落或摺疊區）
- 參考文件中的範例 → 保持克制，只做用法說明，不混入教學
量化基準速查
以下僅為按語言和讀者調整的初篩提示；詳見 校驗清單。
| 維度 | 建議起點 | 使用邊界 |
|---|---|---|
| 英文句長 | 約 20 詞後留意嵌套 | 不機械套用中文，不拆壞條件和契約 |
| 段落 | 一段一個主要觀點 | 例外與警告可緊隨原段 |
| 列表/步驟 | 較長時考慮分組 | 不為湊項數刪除完整步驟 |
| 被動語態 | 主體不清時改寫 | 不設必須達標的比例 |
| Mermaid | 節點多時考慮概覽與細節 | 以實際渲染可讀性判斷 |
| 表格 | 寬表考慮拆分或轉置 | 保留比較所需列與單位 |
數字是建議，不是行業合格標準或研究定律；不為達標改變事實、合約、安全或法律文字。
反模式速查
| 反模式 | 症狀 | 解法 |
|---|---|---|
| Almighty Thud | 巨無霸文件，所有資訊等權，關鍵決策被淹沒 | 拆分或加優先級分層 |
| 型別混寫 | 教學裡塞 API 參考，參考裡寫「為什麼」 | 按 Diátaxis 拆開 |
| 重複鋪墊 | 無實質資訊的引導語 | 精簡措辭，保留風險與步驟資訊 |
| 同義詞漂移 | 同一功能用不同詞稱呼 | 統一術語 |
| 關係不清 | 分支或箭頭含義需猜測 | 為不明確的關係補標籤 |
| chartjunk | 表格加多餘裝飾線、底紋 | 刪除不傳遞資訊的裝飾 |
| 範例過載 | 窮舉所有場景的範例 | 只留最常見用例 |
| 平行維護 | 同一事實在多處獨立維護 | 留一處，其餘改連結 |