「程式碼即文件」是一句聽起來很美的話，但現實是：六個月後連你自己都看不懂自己寫的 API。好的技術文件不只是補充說明，它決定了一個開源專案能否被採用、一個 API 能否被正確使用、一個新工程師能否在兩週內上手。本文從技術文件的分類出發，帶你建立一套可執行、可維護的文件撰寫體系。
一、技術文件的四種類型
著名的文件框架 Diátaxis 把技術文件分成四個象限，每種類型有不同的目的和受眾：
| 類型 | 目的 | 典型範例 |
|---|---|---|
| 教學（Tutorial） | 引導初學者完成第一次成功體驗 | 「5 分鐘快速上手」 |
| 操作指南（How-to Guide） | 解決特定問題的步驟說明 | 「如何設定環境變數」 |
| 參考（Reference） | 精確描述系統的完整技術規格 | API 端點文件、設定參數列表 |
| 解釋（Explanation） | 說明背後的設計理念與概念 | 架構決策紀錄（ADR） |
大多數工程師只寫「參考」類文件（列 API 端點），卻忽略了「教學」和「操作指南」——而後者往往是使用者最需要的。
二、README：專案的第一印象
README 是開源專案或內部庫的門面，它決定了陌生人是否願意繼續讀下去。一份合格的 README 應包含：
- 一句話描述：這個東西是什麼、解決什麼問題
- 快速上手（Quick Start）：最少 3 步讓人跑起來，包含安裝指令
- 使用範例：最典型的使用場景，附程式碼
- 設定說明：環境變數、設定檔格式
- 貢獻指南：如何回報 Bug、提交 PR
- 授權條款：開源協議（MIT、Apache 2.0 等）
常見 README 錯誤
- 假設讀者已知背景知識（「先安裝 Node.js」但沒說版本要求）
- 範例程式碼已過期但沒人更新
- 只列功能清單，沒有說明使用情境
- 沒有說明這個專案不適合什麼情境（避免誤用）
Markdown 即時預覽：撰寫 README 時，使用Markdown 線上編輯器可以即時預覽格式效果，確認標題層級、表格、程式碼區塊的呈現是否如預期，再貼到 GitHub 上。
三、Markdown 技術文件規範
Markdown 是技術文件的事實標準格式，幾乎所有的 README、Wiki、API 文件、技術部落格都使用它。但「能用 Markdown」和「寫好 Markdown」之間差距不小。
標題層級規範
#（H1）：每份文件只用一個，通常是文件標題##（H2）：主要章節，用於文件大綱###（H3）：子章節，不超過三層（避免 H4 以下）- 不要跳層級：不要從 H2 直接跳到 H4
程式碼區塊最佳實踐
程式碼區塊必須指定語言，才能有語法高亮：
```bash
npm install your-package
```
```json
{
"key": "value"
}
```
```python
def hello():
return "world"
```表格使用時機
表格適合呈現有多個屬性的比較型資料（如 API 參數列表），但不適合用來排版（不要用表格做視覺對齊）。
連結與圖片
- 避免裸 URL，使用有意義的錨點文字：
[設定說明](#configuration) - 圖片要有 alt 文字：
 - 內部連結使用相對路徑，外部連結使用完整 HTTPS
四、API 文件：開發者體驗的核心
API 文件是使用你服務的工程師的「使用說明書」，品質直接影響整合成功率和支援成本。
必要的 API 文件元素
-
端點（Endpoint）描述
列出 HTTP 方法 + 路徑，說明這個端點的用途：
POST /api/v1/users：建立新使用者帳號 -
請求參數（Request Parameters）
分為 Path Parameters、Query Parameters、Request Body，每個參數說明：名稱、類型、是否必填、預設值、範例值 -
請求範例（Request Example）
包含完整的 HTTP headers 和 body，用真實的（非 foo/bar）範例值 -
回應格式（Response Schema）
說明成功和失敗的回應結構，包含所有可能的 HTTP 狀態碼 -
錯誤碼（Error Codes）
列出所有自訂錯誤碼及其含義，說明排除方法
格式化 API 回應範例：撰寫 API 文件時，使用JSON 格式化工具將壓縮的 JSON 整理成易讀的縮排格式，直接貼入文件做為範例，提升可讀性。
OpenAPI / Swagger 規範
對於 RESTful API，建議採用 OpenAPI 3.0 規範撰寫 API 定義（YAML 或 JSON 格式）。優點是：
- 自動生成 Swagger UI 互動式文件，讓使用者直接在瀏覽器試打 API
- 可用工具（如 Postman、Insomnia）匯入規格，自動建立測試請求
- 可從程式碼自動生成（如 FastAPI、SpringDoc 等框架原生支援）
- 結構化格式容易版本控制和 diff 比對
五、Docs as Code：把文件當程式碼管理
「Docs as Code」是一種把文件版本控制、審查流程、持續整合同樣套用到文件的工程方法：
核心實踐
- 文件與程式碼同 PR：修改 API 行為時，同一個 PR 必須包含文件更新，缺少文件更新的 PR 不得合併
- 文件審查（Doc Review）：非技術背景的人參與審查，確認描述是否清晰易懂
- 連結有效性檢查：CI/CD 自動掃描文件中的壞連結（dead links）
- 範例程式碼測試：README 或教學文件中的程式碼，應作為 CI 的一部分實際執行驗證
比對文件版本差異：文件更新後，使用文字比對工具快速確認新舊版本的差異，適合在 PR 說明中附上變動摘要，或確認翻譯版本的一致性。
六、技術文件的常見缺陷與解法
| 問題 | 症狀 | 解法 |
|---|---|---|
| 文件與程式碼不同步 | 按文件操作卻出錯 | Docs as Code + CI 驗證範例 |
| 只有快樂路徑 | 遇到錯誤不知道怎麼排除 | 加入錯誤碼說明和排除步驟 |
| 假設讀者有同等背景 | 初學者看不懂，中級者覺得廢話 | 明確定義目標受眾，分層撰寫 |
| 沒有範例 | 使用者不知道如何開始 | 每個功能至少一個完整可執行的範例 |
| 版本資訊缺失 | 不知道這份文件對應哪個版本 | 文件頂部標示版本號和最後更新日期 |
七、讓文件保持更新的工程機制
文件腐化（Documentation Rot）是技術文件最常見的問題——文件在寫完的那一刻開始過期。以下機制可以延緩腐化速度：
- 文件擁有者（Doc Owner）：每份重要文件指定一個維護負責人，季度檢查
- 自動化測試文件範例：教學文件中的程式碼片段加入 CI，讓錯誤不被忽視
- 使用者回饋管道：在文件頁面底部加入「這份文件有幫助嗎？」按鈕和問題回報連結
- Changelog 習慣：每個版本都維護 CHANGELOG.md，說明新增、變更、棄用、移除的項目
- 「此功能待文件」標記：未完成的文件部分用 TODO 或警告標記，比完全不說更誠實
總結
- 技術文件分四類：教學、操作指南、參考、解釋——大多數專案只有「參考」是不夠的
- README 是第一印象，必須在 3 步內讓人成功執行，並附有真實的範例
- Markdown 有明確的最佳實踐：標題不跳層、程式碼指定語言、連結有意義的錨點文字
- API 文件必須包含：端點說明、所有參數、請求範例、回應格式、錯誤碼
- Docs as Code：文件與程式碼同 PR、同審查、同 CI，是讓文件持續更新的根本機制