Writing docs

Skill yanchen184/yc-plugin/skills/writing-docs

寫或改任何技術文件（README / SPEC / sidebar / index / 架構文件 / API 說明 / config 註解 / UI 文案）時用。強制三條風格紀律——文件只寫現狀不留歷史考古、禁自我推銷與裝飾標題、中性事實描述。刪檔或重構後掃導覽檔移除死連結與「已刪除/已取代」註記。From its SKILL.md

Install

npx -y skills add yanchen184/yc-plugin --skill writing-docs

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

5.4 KB, as published. Nobody here has run it

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

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

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

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

文件是給零上下文讀者讀的。 未來打開文件的人不知道有過舊檔、不知道某欄位以前叫什麼。「舊 X 已刪除」對他是純噪音，還憑空製造一個他得去理解的「消失的東西」，等於在乾淨文件上留疤。
狀態 vs 事件的職責分工。 文件 = 狀態（現在是什麼）；git / CHANGELOG = 事件（發生過什麼、怎麼變）。把「刪了什麼」寫進文件 = 拿文件記事件 = 職責錯位 + 雙重來源 + 會 rot。
這跟 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 描述：這裡才是寫「改了什麼、為什麼變」的地方——歷史歸這裡，不歸文件

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

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