writing-docs

writing-docs — 技術文件風格紀律

核心一句話：文件描述「現在是什麼」，不描述「過去發生過什麼」、不自我推銷、不裝飾。 讀者是零上下文的人（新人、未來的你），把文件寫得像它一直就長這樣。

這是 rigid skill——三條紀律照做，不要「視情況放寬」。

---

為什麼存在（底層邏輯，記住才能判邊界）

1. 文件是給零上下文讀者讀的。 未來打開文件的人不知道有過舊檔、不知道某欄位以前叫什麼。「舊 X 已刪除」對他是純噪音，還憑空製造一個他得去理解的「消失的東西」，等於在乾淨文件上留疤。
2. 狀態 vs 事件的職責分工。 文件 = 狀態（現在是什麼）；git / CHANGELOG = 事件（發生過什麼、怎麼變）。把「刪了什麼」寫進文件 = 拿文件記事件 = 職責錯位 + 雙重來源 + 會 rot。
3. 這跟 code 紀律同源。 code 早就規定「不留 // removed 註解、不 re-export 已刪的東西、不留 backwards-compat shim」。文件、config 註解、API schema、UI 文案全是「描述現狀的產物」，同一套邏輯。

---

三條紀律

紀律 1：只寫現狀，不留歷史考古

刪檔、重構、取代舊文件之後，文件本身禁止留任何「過去發生過什麼」的註記。

禁止字眼／形式（打出來立刻刪）：

• 「舊的 X 已被 Y 取代並刪除」
• 「已歸檔 / 已移除 / 已棄用，需考古請看 git commit XXX」
• 「先前版本…」「原本是…現在改成…」
• 任何指向「已不存在的東西」的對照句、死連結說明
• 在 README / SPEC / sidebar 結尾掛「歷史決策見 _archive/…」這種指引

正確做法只有兩件事：(a) 移除死連結；(b) 確認剩下文字讀起來像「一直就這樣」。真要考古的人去 git 找，那是 git 的職責。

紀律 2：禁自我推銷與裝飾標題

技術文件就是技術文件，不要寫成行銷文宣。內容好不好讓讀者自己判斷，文件不需要推銷自己。

禁止字眼／形式：

• 「消化版」「消化過」「精華版」「重點整理」「可以直接念」「直接念稿」
• 「開會主用這份」「會議用」「給主管看」「（被會議延伸問到時翻）」這類使用情境定位句
• 裝飾性類別標題如「🎯 內部會議用」「📚 細部資料」
• 標題加 ⭐🔥 等強調 emoji
• 標題附註「（消化版）」「（精華版）」

例外：臨床／領域術語的「首選」不算自誇（例：「高血壓首選藥」）。

紀律 3：中性事實描述

描述每份文件 / 每個項目用中性事實句，不加價值判斷形容詞。

• ✅「決策清單（已拍板 36 條 + 未拍板）」「Hermes 九環節主流程」
• ❌「重點整理」「必看」「給誰看」「最完整的一份」

導覽檔（README / index / sidebar）用扁平條列 + 中性描述，不加分類 section、不加自誇形容詞。

---

好壞對照

❌ 違規	✅ 修正
> 舊的 01-13 散落文件已被 SPEC 完整取代並刪除，考古見 git cb4961a	（整行刪除，不留痕）
## 📚 細部資料（開會主用這份）	## 細部資料
SPEC（消化版，可以直接念）	SPEC · 系統規格書
這個欄位以前叫 user_name，現在改成 username	username — 使用者帳號
[已棄用] 舊架構圖見 _archive/01-架構.md	（連結與整句一起刪）
★ 最完整的一份，必看	系統規格書

---

套用流程

寫新文件時

逐句自檢三條紀律。標題只寫主題本身，描述用中性事實句。

刪檔 / 重構後（最容易漏）

掃過所有會提到被刪物的檔案——README / index / sidebar / SPEC 開頭與結尾 / 任何導覽檔——把考古句、對照句、指向已刪物的連結全部刪乾淨，不是改寫成「已刪除」。

可用 /docs-lint <檔案或目錄> 自動掃一輪揪出殘留違規字眼與死連結。

review 既有文件時

主動掃這些字眼移除，不用等人再講一次。

---

推廣面（不限 docs）

這三條不限技術文件。任何「描述現狀」的產物都適用：

• config 註解：不要留「這個設定以前是…」
• API schema 說明：不要留「v1 用的欄位，v2 已移除」
• UI 文案：不要留過去式對照
• commit body / PR 描述：這裡才是寫「改了什麼、為什麼變」的地方——歷史歸這裡，不歸文件

---

自我罵點（看到自己犯就糾正，不等人罵）

1. 刪檔後在 README/SPEC 留「舊 X 已刪除／考古見 git」→ 違規（紀律 1）
2. 標題出現「消化版／開會用／必看」或裝飾 emoji → 違規（紀律 2）
3. 描述加價值判斷形容詞而非中性事實 → 違規（紀律 3）
4. 刪檔後沒掃導覽檔、留死連結 → 違規（套用流程）