跳轉到

教學文件模板（Template）

來源風格：google-cloud-project-setup.md 註：本檔內 ./xxx.md、[URL]、./next.md 等皆為模板占位符，非實際連結。

1) 結構提煉（Structure）

  1. 標題 + 一句話目的
  2. 前置關聯（此文件是什麼前置/下一步）
  3. 如果你已經熟悉 XXX 流程（熟悉者可直接照做的精簡步驟）
  4. 快速總覽（幾大步驟、最終產出）
  5. 準備工作（進入頁面、工具準備）
  6. 主流程 Step 1 ~ Step N（每步含子步驟）
  7. 敏感/關鍵提醒（NOTE / IMPORTANT）
  8. 常見問題 / 疑難排解
  9. 結果落地（寫入 .env 或系統設定）
  10. 完成檢查清單
  11. 下一步導引
  12. 官方參考資料

2) 寫作理念（Writing Principles）

  • 任務導向：每一步都服務於「最終可運行」的目標。
  • 行動語句：使用「點擊 / 輸入 / 選擇 / 確認」等可執行動詞。
  • 可驗證性：每步都附「您會看到」，讓讀者知道是否做對。(請不要加粗體)
  • 降低迷路成本：跨文件連結清楚標示前後依賴。
  • 防呆與安全：在易錯點加 IMPORTANT，在可跳過情境加 NOTE。
  • 新手友善：搭配截圖、按鈕名稱、路徑名稱，避免抽象描述。
  • 說明與操作分離：前提條件、測試範圍、角色差異這類說明，優先放在簡介區，不要塞進 Step。
  • 可先定義動詞：若文件中會反覆使用像「執行」「開啟」「儲存」這類動詞，可以在前面用一個 NOTE 統一說明這個動詞在本文中的意思；不用在每個步驟重覆解釋。
  • 避免重複：前置條件只集中說一次；前言與 IMPORTANT 不要重覆列出同一批內容。
  • 疑難排解獨立：404、埠衝突、權限問題等故障排除，獨立放在「常見問題」區塊，不混入正常流程。

3) 風格特點（Characteristics）

  • 大綱先行：先給全局四步驟，再進入細節。
  • 層級清晰：Step x.y 拆解細緻，便於定位問題。
  • 結果導向句型固定：每條操作後接「您會看到：...」。
  • 高可操作性：包含可直接複製的連結、指令、範例值。
  • 風險提示明確：機密資訊、常見錯誤（如 redirect URI）單獨警示。
  • 流程純化：Step 只保留需要實際執行的動作；若有共通動詞需要說明，集中在前面的 NOTE 處理，不要把每個動作都再定義一次。

5) 圖片協作規則（與 AI 配合）

圖片路徑規則

  • 教學圖片統一放在 docs/tutorial/photo/[文件名稱]/[步驟資料夾]/
  • 範例：
  • docs/tutorial/photo/google-cloud-project-setup/step3-create-oauth-client/
  • docs/tutorial/photo/litellm-proxy-setup/step2-config-file/
  • 不要把 Step 圖片長期混放在 docs/tutorial/photo/ 根目錄
  • 每個主教學文件都應有自己的子資料夾，避免不同教學互相覆蓋圖片

圖片命名規則

  • 先用描述動作的英文檔名
  • 建議格式：stepX-action-description.png
  • 範例：
  • step3-select-web-application-type.png
  • step3-fill-redirect-uris-8788-and-8000.png
  • step3-open-json-find-client-secret.png
  • 檔名要能反映「畫面在做什麼」，不要長期保留 image.png

與 AI 的合作方式

  1. 您先把最新截圖暫時存成： docs/tutorial/photo/image.png
  2. 在對話中告訴我：
  3. 圖片路徑
  4. 這張圖要放在哪個步驟
  5. 想強調的動作或文字
  6. 我會負責：
  7. 將 docs/tutorial/photo/image.png 分類移到正確的教學子資料夾
  8. 將 image.png 改成正式檔名
  9. 更新 Markdown 圖片引用
  10. 視需要同步調整步驟敘述
  11. 若您說「替換原本那張」，我會優先沿用原引用位置，只替換圖片檔或路徑
  12. 若您說「重新加回來」，我會依現在文件結構重新整理圖片位置與文字，不假設舊路徑仍然有效

注意事項

  • 圖片更新後，可能不需要改文字；但若畫面流程或按鈕名稱變了，應一起更新敘述
  • 若新圖片結構與舊引用不一致，先修引用，再決定是否重寫段落
  • 若同一步有多張圖，應讓每張圖各自對應一個操作重點，避免一張圖承載過多資訊
  • 圖片應緊跟在它對應的操作步驟後面，不要等整個 Step 寫完才集中放圖
  • 若一個子步驟內有多張圖，請依操作順序分別插在對應條目後，讓讀者能邊做邊對照畫面

5) 可複用 Markdown 模板

# **[教學標題]**

本文檔涵蓋如何 [一句話描述目標]。

此為[前置文件](./xxx.md)的後續步驟，也是後續[下一份文件](./yyy.md)的必要條件。

> [!NOTE]
> [可跳過條件 / 角色差異 / 快速路徑]

---

## 簡介：完整設定流程

本指南分為 [N] 個主要步驟，從 [起點] 到 [終點]。

> 最終目的: 取得 `[關鍵輸出 A]` / `[關鍵輸出 B]`，填入 `[目標位置]`。



**TOC**
- [準備工作](#準備工作)
- [Step 1：[主步驟名稱]](#step-1主步驟名稱)
- [Step 2：[主步驟名稱]](#step-2主步驟名稱)
- [Step 3：[主步驟名稱]](#step-3主步驟名稱)
- [Step 4：[配置 / 落地步驟]](#step-4配置--落地步驟)
- [常見問題](#常見問題)
- [完成後檢查清單](#完成後檢查清單)
- [下一步](#下一步)
- [官方文檔參考](#官方文檔參考)

## 如果你已經熟悉 [主題] 流程

如果您已熟悉整體流程，可先依下列精簡步驟完成配置：
如果您不熟悉，請直接從下方「準備工作」開始，依序完成完整流程。


1. [快速步驟 1]
2. [快速步驟 2]
3. [快速步驟 3]
4. [快速步驟 4]

### [N] 大步驟概覽
這裡先提供流程概覽，幫您快速掌握整體有哪些步驟，以及每一步會帶來的結果。

1. **[步驟名稱 1]**
   - **目的與效果**：[因為要達到 XXX 的效果，所以做這步]
   - **完成後您會得到**：✅ [可驗收成果]

2. **[步驟名稱 2]**
   - **目的與效果**：[因為要達到 XXX 的效果，所以做這步]
   - **完成後您會得到**：✅ [可驗收成果]

> [!NOTE]
> **關於「執行」**：[如有命令列操作，寫清楚「複製 → 貼上 → Enter」]

> [!IMPORTANT]
> [前提條件 / 測試範圍 / 可先驗證與需後驗證的內容，優先集中寫在這裡，不要拆成純說明型 Step]

---

## **準備工作**

1. **[操作動詞]** [具體動作]
   您會看到：[可觀察結果]

![準備工作截圖 1](./photo/[path]/[image-1].png)

2. **貼上** 以下網址並按 Enter：
   [連結]([URL])
   ```
   [URL]
   ```
   您會看到：[可觀察結果]

![準備工作截圖 2](./photo/[path]/[image-2].png)

---

## **Step 1：[主步驟名稱]**

### Step 1.1：[子步驟名稱]

1. **[操作]** [內容]
   您會看到：[可觀察結果]

![Step 1.1 截圖 1](./photo/[path]/[image-1].png)

2. **[操作]** [內容]
   您會看到：[可觀察結果]

![Step 1.1 截圖 2](./photo/[path]/[image-2].png)

### Step 1.2：[子步驟名稱]

1. **[操作]** [內容]
   您會看到：[可觀察結果]

![Step 1.2 截圖](./photo/[path]/[image].png)

> [!IMPORTANT]
> [易錯點 / 限制條件 / 失敗訊息與原因]

---

## **Step 2：[主步驟名稱]**

### Step 2.1：[子步驟名稱]

1. **[操作]** [內容]
   您會看到：[可觀察結果]

![Step 2.1 截圖](./photo/[path]/[image].png)

---

## **Step 3：[主步驟名稱]**

### Step 3.1：[子步驟名稱]

1. **[操作]** [內容]
   您會看到：[可觀察結果]

![Step 3.1 截圖 1](./photo/[path]/[image-1].png)

2. **複製** `[關鍵值 A]`、`[關鍵值 B]`
   您會看到：[值已取得]

![Step 3.1 截圖 2](./photo/[path]/[image-2].png)

> [!IMPORTANT]
> **安全提醒**
> - `[敏感值]` 不可上傳版本控制
> - 若外流，請 [補救措施]

> [!NOTE]
> 若文件中還會反覆出現其他動詞，也可以比照這種方式統一定義。例如：
>
> **關於「開啟」**：本指南中的「開啟 [檔案 / 頁面]」表示：
> 1. 找到指定檔案或頁面
> 2. 用編輯器或瀏覽器打開
>
> **關於「儲存」**：本指南中的「儲存」表示：
> 1. 完成目前修改
> 2. 按下 `Ctrl + S`

---

## **Step 4：[配置 / 落地步驟]**

### Step 4.1：開啟設定檔

1. **進入** [專案路徑]
2. **開啟** `[檔案名稱]`
   您會看到：[檔案開啟成功]

### Step 4.2：填入設定

```env
[KEY_1]=[VALUE_1]
[KEY_2]=[VALUE_2]

您會看到：[設定值已填入]

Step 4.3：儲存

  1. 按下 [快捷鍵] 您會看到：[檔案已儲存]

[!NOTE] 像更新 .env、編輯設定檔這類步驟，通常直接寫「開啟 → 加入 / 修改 → 儲存」即可，不需要另外定義每個動作。

常見問題

Q：[常見錯誤 1]？
A：[簡短排查方式與修正方向]

Q：[常見錯誤 2]？
A：[簡短排查方式與修正方向]

完成後檢查清單

  • [ ] [關鍵設定 A] 已完成
  • [ ] [關鍵設定 B] 已完成
  • [ ] 未洩露敏感資訊

下一步

  1. 前往 下一步文件
  2. 執行 [下一階段任務]

官方文檔參考

  • [主題 A] [URL]
  • [主題 B] [URL] ```