技術文件失敗的最常見原因不是「沒有文件」——是「文件的讀者是誰」從來沒有被想清楚。
一份 README 裡塞了「快速開始教學 + API 參考 + 設計決策說明 + 常見問題排查」，結果每種讀者都找不到自己要的東西。
Diátaxis 框架（Daniele Procida 提出）把文件分成四個象限，每個象限有不同的目的和寫法。
四種文件類型
學習導向 工作導向
實踐型 ┌──────────┬──────────────┐
│ Tutorial │ How-to Guide│
├──────────┼──────────────┤
理論型 │Explanation│ Reference │
└──────────┴──────────────┘
Tutorial（教學）
目的：帶初學者完成一個有意義的旅程，建立信心。
讀者狀態：不知道要問什麼問題，需要被帶著走。
寫法原則：
- 每一步要確實可執行，不要跳步
- 結果要立刻可見（做了就能看到效果）
- 不要在中途解釋為什麼——先做，之後 Explanation 再解釋
- 不要給選項（「你也可以用 X 或 Y」）——選一條路走到底
反例：「安裝後，根據你的需求設定 config」——初學者不知道自己的需求是什麼。
How-to Guide（操作指南）
目的：讓已經有目標的人完成一個具體任務。
讀者狀態：知道自己要做什麼，需要找方法。
寫法原則：
- 標題是動詞短語：「如何設定 HTTPS」「如何遷移資料庫」「如何排查 OOM 問題」
- 直接從解法開始，不要重複背景介紹
- 假設讀者有基礎——不是在教他們什麼是 HTTPS
跟 Tutorial 的差別：Tutorial 從零帶你到有，How-to Guide 是「我已經在路上了，這個具體問題怎麼解」。
Reference（參考手冊）
目的：提供準確完整的技術細節，供查詢。
讀者狀態：知道要找什麼，需要精確資訊。
寫法原則：
- 乾、準、全——不要有解釋性文字，只有事實
- 結構化（表格、清單），方便掃描
- 每個 API endpoint、每個 config 選項、每個 CLI flag 都要在這裡
API documentation 本質上是 Reference。 Swagger / OpenAPI spec 生成的文件就是這個類型。
Explanation（說明）
目的：幫助讀者理解 why——背景、設計決策、概念。
讀者狀態：想要深入理解，不急著操作。
寫法原則：
- 從 why 和 how 的角度談，不是 what
- 可以有不同視角、取捨說明、歷史背景
- 不要給操作步驟
Architecture Decision Record（ADR）就是 Explanation。 「為什麼選 PostgreSQL 而不是 MongoDB」這類文件屬於這個類型。
好的 Documentation System Checklist
- 每份文件有明確的類型（四選一），寫法對應類型目的
- 有版本標記或 last updated 日期
- Code example 是可以直接跑的，不是偽代碼
- 有搜尋功能（Docusaurus、GitBook、Notion 都有）
- 文件和 code 在同一個 repo，PR 時一起改（防止文件落後 code）
- 有 broken link 自動檢查
- 有 on-call runbook，每個 alert 連到對應的 How-to Guide
最小可行的文件體系
不需要一開始就全部齊備。優先順序：
- README：這個 repo 是幹什麼的、如何在本機跑起來（Tutorial 前半）
- CONTRIBUTING：如何提 PR、如何設定開發環境（How-to Guide）
- API Reference：endpoint、參數、response schema（Reference）
- ADR：關鍵設計決策（Explanation）——不需要很多，十幾份就夠
文件最大的敵人是「過時」。有更新 code 時沒有更新文件，文件就變成謊言。把文件 review 加進 PR checklist，是維持文件品質成本最低的方式。