團隊文件要長得差不多、看得懂，靠的是兩份模板和一條原則。原則是寧可少而新鮮：Google 的文件指南說，少量但新鮮正確的文件，勝過大量年久失修的文件，別處有的就連過去。how-to 模板照「先決條件、步驟、怎麼確認成功、出問題找誰」排；一項研究裡，照模板改寫的安裝說明在讀者評分的十個面向中有八個較好。決策紀錄（ADR）記下當時為什麼這樣決定，推翻時不刪、標成「已被取代」並連到新決定。研究也看到 ADR 常常試了沒繼續、「考慮過的選項」那段問題最多，常常沒寫或寫錯地方，所以模板要短，那一段要留著。
文件過時是常態，而且不會報錯。GitHub 最熱門的專案裡，八成曾在文件裡留下指向已刪除程式碼的引用。維護有四種做法：每頁掛一個負責的角色、設驗證到期、改流程時同一個變更裡改文件、在被用到的時候順手改。每一種都有失靈的方式：負責人離職、到期通知被當垃圾信、規定在但沒人照做、沒人用的文章永遠沒人檢查。刪除的原則是先刪確定錯的，正確但少用的封存。讀完你能替團隊訂一張維護規則表：文件類型、負責角色、確認週期、刪除條件。
團隊 wiki 會爛掉，研究看到的主要是三件事：缺漏和過時比寫錯更常被抱怨、寫的人沒時間或離職了、主管和實際寫的人要的東西不一樣。不是所有 wiki 都會爛：寫的人自己也是讀的人，或文件解決的是一個明確的問題時，比較撐得住。文件可以照 Diátaxis 分成四種：教學、操作指南、參考資料、說明，用兩個問題判斷一份文件該是哪一種，就能看出團隊缺哪一類。
開放教科書和付費教科書相比，22 個研究合起來學習表現沒有可靠差異（g = 0.01），退選較少但證據較弱；加州四套審定的數學教科書裡，一套比另外三套合起來高約 0.05 個標準差。極簡設計的教材（多數是改寫過的手冊）效果很大，但研究老、樣本小、沒經過期刊審查。「一對多的解說划算」和 Diátaxis 的四分法都是論證，不是資料；把一門課重新講一次，目前沒有研究直接測過。
沒有「不寫註解」派，只有「預設不寫、例外才寫」（Uncle Bob）和「註解是設計的一部分」（Ousterhout、antirez）。兩人 2024–2025 的公開對談裡，雙方都同意 why 註解要寫、廢話註解不要寫；真正吵的是方法的介面註解、長名字能不能取代註解，以及該不該信任註解。實證研究的結論是看品質：同一批受試者，註解讓表現從下降 30% 到提升 34% 都有。
llms.txt 是 Jeremy Howard 於 2024-09-03 提出的慣例（規範已更新至 v2）：在網站根目錄放一份給 LLM 讀的 Markdown 索引。六個前端文件站實測：TanStack、shadcn、Zustand、AI SDK、Next.js 都有，React Router 是唯一 404。配套的 llms-full.txt（全文版）Anthropic、Cloudflare 等也已採用。這篇講規範內容、誰在用、以及它為什麼開始影響套件選型。
GitBook 是一個以 Git 為底層的文件平台，支援 Markdown 編輯、版本控制、多人協作。適合技術文件、API docs、內部知識庫。免費方案對個人和小團隊夠用。
九個主流文件平台的定位、優缺點、適用場景和實際使用案例。選擇邏輯：開源專案選 Docusaurus/VitePress，API docs 選 Mintlify/ReadMe，企業內部選 Confluence，快速上手選 GitBook。
OpenClaw 有 200+ 份文件，這篇幫你搞懂全貌、知道每塊在講什麼、依你的角色決定從哪讀起。
Debug 完直接說「把錯誤寫成文章」，Claude Code 會從對話裡萃取內容，套用模板、生成 frontmatter、commit 到 repo。不需要額外寫任何東西。