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

### Diátaxis 文件四象限
依讀者意圖組織內容，避免混用：

| 類型 | 讀者問題 | 結構特徵 | AI 產品範例 |
|------|----------|----------|-------------|
| **Tutorial** | 我想學習 | 線性、手把手、可完成小專案 | 「30 分鐘建立你的第一個 RAG 應用」 |
| **How-to Guide** | 我想解決問題 | 目標導向、假設已有基礎 | 「如何處理 streaming response 中斷」 |
| **Reference** | 我需要查規格 | 完整、精確、可搜尋 | API 參數表、model card、error codes |
| **Explanation** | 我想理解原理 | 概念性、脈絡、取捨 | 「為何選擇 embedding 而非 keyword search」 |

### Docs-as-Code 工具鏈
- **格式**：Markdown / MDX、AsciiDoc；結構化 API 用 OpenAPI 3.x
- **靜態站點**：Docusaurus、MkDocs Material、VitePress、ReadMe、GitBook
- **版本化**：URL path versioning（`/docs/v2/`）或 docs banner 標示版本
- **CI 檢查**：markdownlint、vale（prose lint）、link checker、OpenAPI validator、snippet extract test
- **單一來源**：從 OpenAPI 生成 reference；從 code comments 生成 SDK docs

### AI/ML 文件專項清單

#### Model Card 必備區塊
- Model overview（架構、訓練資料概述、intended use）
- Performance metrics（benchmark、eval set、已知失敗模式）
- Limitations & biases
- Ethical considerations & safety mitigations
- Environmental impact（可選）

#### LLM 整合文件必備
- System vs user prompt 職責划分
- Context window 與 token 計費說明
- Streaming、function calling、JSON mode 行為差異
- Rate limits、retry with exponential backoff 範例
- Prompt injection 防護建議（輸入驗證、輸出過濾、human-in-the-loop）

#### RAG 文件必備
- Chunking 策略取捨表
- Embedding model 與 index 維度對齊
- Retrieval + rerank 管線圖（文字描述即可）
- 評估指標：recall@k、faithfulness、answer relevance

### Information Architecture 原則
```
首頁
├── Getting Started（Tutorial 為主）
├── Guides（How-to）
├── API Reference（自動生成 + 人工補充）
├── Concepts（Explanation）
├── SDKs & Tools
├── Changelog & Migration
└── Support / FAQ / Troubleshooting
```

**導覽規則**：
- 左側 nav 依使用者旅程排序，非依工程組織架構
- 每個產品線最多 2 層深度進入核心任務
- Search 同義詞表：將「向量」「embedding」「semantic search」互聯

### 審稿與發布流程（Documentation Review Cycle）
1. **Author self-review**：對照 checklist + 本地 build preview
2. **Technical review**：工程師驗證程式碼與 API 行為
3. **Editorial review**：術語、可讀性、IA 連結
4. **Legal/Security review**（若適用）：合規、資料處理、export control
5. **Release alignment**：文件與 API/SDK 版本同步上線；feature flag 文件需標狀態

### 文件 Metrics & 改善
| 指標 | 定義 | 目標方向 |
|------|------|----------|
| TTFS | 新用戶至第一次成功 API 200 的時間 | ↓ |
| Search success rate | 站內搜尋後未立即離開的比例 | ↑ |
| Support deflection | 文件涵蓋後支援工單降比 | ↑ |
| Freshness score | 最後驗證日期距今 | ↓ 天數 |
| Broken link rate | CI 偵測失效連結比例 | → 0 |

### 常用交付物模板意圖
- **Quickstart**：Prerequisites → Step 1-5 → Verify success → Next steps
- **Concept page**：What → Why → How it works → Trade-offs → Related
- **Migration guide**：Timeline → Breaking changes table → Codemod/script → FAQ
- **Deprecation notice**：替代方案 → EOL date → 影響範圍 → 升級路徑

### 與其他團隊協作話術
- 對工程：「這個 edge case 會讓 20% 整合失敗，建議在 reference 加註 + sample。」
- 對 PM：「changelog 需要明確 breaking change，否則 NPS 會在升級週受損。」
- 對法務：「我們需要資料保留期限的一句話摘要置於 signup 前可見處。」