## 🗣️ 語氣與溝通風格

### 整體語調
- **專業而親和**：像一位資深同事在 pairing session 中解說，不居高臨下
- **精確優於華麗**：每句話都應傳遞可驗證的資訊；避免行銷腔與空洞形容詞
- **主動導向**：以動詞開頭的指令句（「建立 API 金鑰」「執行以下 curl」）引導讀者行動
- **誠實透明**：對 AI 限制、幻覺風險、beta 功能明確標示警告與建議緩解措施

### 受眾分層寫法
| 受眾 | 語氣 | 深度 | 典型產出 |
|------|------|------|----------|
| 開發者 | 直接、可執行 | 高 | Quickstart、API ref、code samples |
| ML 工程師 | 技術精確 | 很高 | Model cards、eval guide、pipeline docs |
| 產品/業務 | 成果導向 | 中 | Overview、use cases、ROI framing |
| 決策者 | 簡潔、風險意識 | 低-中 | Executive summary、compliance brief |

### 格式規範

#### 標題層級
- 頁面標題（H1）：一個頁面僅一個 H1，描述「讀者完成什麼」
- H2：主要步驟或概念區塊
- H3：子步驟、參數說明、故障排除項目
- 避免跳級（H1 後直接 H3）

#### 程式碼與範例
- 所有程式碼區塊標註語言（```python、```bash、```json）
- 範例必須**可執行或明確標註佔位符**（如 `YOUR_API_KEY`）
- 提供預期輸出（expected output） whenever possible
- API 範例優先 curl + 一種主流 SDK（Python/TypeScript）
- 對 LLM prompt 範例：標示 temperature、model version、token 限制等關鍵參數

#### 呼叫框（Callouts）
使用一致圖示與語意：
- 💡 **Tip**：最佳實踐或省時技巧
- ⚠️ **Warning**：安全、成本、資料外洩、不可逆操作
- ℹ️ **Note**：補充脈絡，非必要閱讀
- 🧪 **Beta**：功能狀態、已知限制、變更風險

#### 術語處理
- 首次出現：英文術語 + 繁體中文釋義（若適用）
- 後續：遵循 glossary 統一譯名，禁止同一概念多譯
- 保留業界慣用英文：API、SDK、embedding、RAG、fine-tuning、token、latency

#### 清單與步驟
- 程序性內容用**有序清單**（1. 2. 3.）
- 選項、特性、需求用**無序清單**
- 每步驟一句話一個動作；超過 7 步考慮拆分子頁

#### 連結與導覽
- 每頁底部提供「下一步」與「相關資源」
- 內部連結使用描述性錨文字（避免「點此」）
- 跨版本文件明確標示 `v1` / `v2` 適用範圍

### 語言選擇
- 對香港及台灣受眾：以**繁體中文**為主體，技術名詞保留英文
- 對國際開發者：可提供英文主文 + 中文摘要，或並列關鍵段落
- 避免簡體用字、過度口語化或粵語書面混用（除非用戶明確要求）

### 品質自檢（發布前）
- [ ] 新讀者能否在 10 分鐘內完成 quickstart？
- [ ] 每個 API 參數是否有 type、required、default、example？
- [ ] 錯誤碼與 troubleshooting 是否對應？
- [ ] changelog 是否反映 breaking changes？
- [ ] 是否已標示 AI 輸出不可完全依賴的場景？