## 🛠️ 專業框架與方法論

### 文件類型精通
| 類型 | Diátaxis 分類 | 典型結構 |
|------|---------------|----------|
| 入門指南 | Tutorial | 學習路徑、手把手步驟、預期成果 |
| 操作指南 | How-to | 目標導向、假設讀者已有基礎 |
| 概念說明 | Explanation | 背景、設計決策、權衡 |
| API/Reference | Reference | 參數表、型別、範例請求/回應、錯誤碼 |
| Runbook | How-to + Reference | 觸發條件、診斷樹、升級路徑 |
| ADR | Explanation | Context → Decision → Consequences |
| Release Notes | Reference | Added/Changed/Fixed/Deprecated/Security |

### Diátaxis 框架
撰寫前先問：**讀者要學習、完成任務、理解概念，還是查資料？** 一篇文件只服務一種意圖；混雜時主動建議拆分。

### Docs-as-Code 工具鏈
- **格式**：Markdown、MDX、AsciiDoc、reStructuredText
- **靜態站點**：Docusaurus、MkDocs、VitePress、GitBook、Read the Docs
- **API 文件**：OpenAPI/Swagger、Redoc、Stoplight、Postman Collections
- **Lint/CI**：Vale、markdownlint、Alex（包容性用語）、自訂 terminology rule
- **版本化**：docs 與 product 版本對齊策略（versioned docs vs. single docs + version tabs）

### 資訊架構（IA）原則
1. **MECE 分類**：互斥且完備的主題分層
2. **Progressive disclosure**：入門 → 進階 → 參考，避免一次淹沒讀者
3. **Diátaxis 四象限**作為頂層導覽錨點
4. **Search-first 設計**：標題、H2、前 160 字含關鍵搜尋詞

### API 文件最佳實踐
- 每個 endpoint：方法、路徑、認證、rate limit、請求/回應 schema、至少一個完整 curl 範例
- 錯誤回應表格：HTTP status、error code、原因、建議處理
- Webhook：payload 範例、重試策略、簽章驗證步驟
- Changelog 與 API 版本策略（URL path vs. header versioning）

### 審核與協作流程
- **RACI**：誰撰寫、誰技術審核（SME）、誰編輯、誰發布
- **PR Review Checklist**：準確性、可讀性、連結、截圖更新、breaking change 標記
- **Dogfooding**：按文件步驟實際操作一遍（或明確標註未驗證）

### 成效衡量
- 支援 ticket 重複問題率、docs 頁面跳出率、搜尋零結果查詢、time-to-first-success
- 定期 content audit：孤兒頁、重複主題、過時版本標籤

### 重構與遷移 playbook
1. 盤點現有內容與流量/支援數據
2. 定義目標 IA 與 redirect 對照表
3. 批次遷移 + 301/alias 設定
4. 設定 deprecation banner 與 sunset 日期
5. 通知內部利害關係人與外部 changelog