writing-training-doc

name: writing-training-doc description: 產出 know why 優先的實作型技術課程文件（Lab、README、名詞導讀、速查表、補充說明）：先建立架構模型，再用操作驗證模型，最後要求學員能從畫面、API、log、資料、設定或輸出結果反查原因。強制檢查前置依賴、Step 銜接、架構責任、資料流、設定影響、可貼上程式碼、主題切分、索引同步與練習驗收。觸發時機：使用者說「寫課程講義」、「產出 Lab 文件」、「整理成操作手冊」、「寫 training doc」、「幫我寫 SOP」、「為 [工具名] 設計課程」、「新人訓練材料」，或任何需要技術教學材料、實作教材、操作指引的情境。

Writing Training Doc

本技能用於產出 know why 優先的實作型課程文件：先建立架構模型，再用可執行、可觀察的小流程驗證模型，最後要求學員從結果反查原因。觀察頁面、Console、API、查詢結果或畫面前，必須先建立或確認依賴資源；尚未出現的頁面、資料或選項，要標示它會在哪個 Step 之後出現。

Know Why 優先原則

技術課程文件以 know why 為主，know how 為輔。每份 Lab 在進入操作前先說明：

1. 本 Lab 主題在整體系統、框架或工具鏈中的位置。
2. 本 Lab 會修改哪些層級、檔案、設定、資料、服務或 runtime 狀態。
3. 這些修改為什麼必要。
4. 操作後可以在哪裡觀察結果。
5. 學員如何從畫面、API、log、資料、設定或輸出結果反查背後原因。

每個重要設定都要說明架構意義與後續影響；指令、點擊流程與程式碼範例只承載操作，不能取代原因說明。

文件類型選擇

所有文件統一輸出為 Markdown（.md）。若無法判斷類型，詢問學員程度與要產出單一 Lab 或整套材料。

目錄與檔名

• docs/：只放主要教學內容，如 README.md、Lab、速查表、補充說明、環境說明。
• repo 根目錄：放環境入口與單檔設定，如 .env、docker-compose.yaml。
• repo 根目錄功能資料夾：放可執行資產，如 mock-api/、scripts/、sample-data/、fixtures/。
• .env 只能提交課程必要且非敏感的預設值；密碼、token、個人路徑與私有連線字串改用 .env.local 並排除版控。
• 環境指令預設從 repo 根目錄執行，不把 docs/ 當啟動入口。

課程檔名編號規則

• 主課 Lab 使用 NN-topic.md。
• 子課 Lab 使用 NN-01-topic.md、NN-02-topic.md、NN-03-topic.md。
• 主課編號保留給該系列的總覽、基礎、主線或入口課程。
• 子課從 01 開始遞增，不使用 NN-00-topic.md。
• 下一個主課系列接續使用下一個 NN-topic.md，其子課同樣從 NN-01-topic.md 開始。

範例：

編號判斷原則：

環境指令範例：

docker compose up -d
docker compose run --rm --no-deps <service-name> <check-command>

實作 Lab 結構

固定開頭：

# Lab NN：<主題>

目標：<一句話說明這個 Lab 要達成什麼>

預估時間：N 分鐘。

必要章節順序：

1. ## 你會做出什麼
   • 用 flowchart LR 畫完成後的資料流或操作流。
   • 圖後用短句說明每個節點責任。
2. ## 開始前先知道
   • 當 Lab 會逐步建立多個依賴資源時加入此區塊，用表格列出頁面、URL、Console、API、資料表、索引、policy、schema、設定檔、使用者、群組或內容資料的出現時機。
   • 這個區塊只說明出現時機，不取代操作步驟。
3. ## 先理解本 Lab 的架構關係
   • 說明主題責任層、會改哪些檔案/設定/資料/服務/endpoint/runtime 狀態、資料如何流動、Step 順序原因，以及結果由哪一層造成。
4. ## Step N：<動詞 + 對象>
   • 每個重大操作一個 Step，內部用有序列表。
   • 參數多於兩個時使用表格：Parameter / Value。
   • 重要設定後加 說明： 解釋架構意義、runtime 影響與下一步關係。
5. ## 練習題
   • 每個重要主題至少有一題，包含狀態承接、操作步驟、確認方式、可觀察結果與反查來源。
6. ## 完成檢查
   • 列學員應理解並能解釋的概念，不只驗收操作完成。
7. ## 排錯提示
   • 用「狀態或訊息特徵、背後原因、處理」描述。
8. ## 本 Lab 的學習重點回顧
   • 重畫整條 flow，說明每個節點與關係，最後點出實際專案意義。

開始前先知道 建議格式：項目 / 出現時機。例如 <resource-a> 會在完成 Step N 後出現。

先理解本 Lab 的架構關係 建議格式：

## 先理解本 Lab 的架構關係

這個 Lab 的主題屬於 <layer-name>。你會先修改 <definition/config/data layer>，再讓 runtime 讀取這些定義，最後從 <page/API/log/output> 觀察行為。

```mermaid
flowchart LR
    Definition["Definition Layer"] --> Runtime["Runtime Behavior"]
    Runtime --> Output["Observable Output"]
```

| 層級 | 本 Lab 會改什麼 | 為什麼必要 | 觀察與反查方式 |
| --- | --- | --- | --- |
| 定義層 | `<file-or-config>` | runtime 需要讀取這份定義 | 從輸出結果反查到設定來源 |
| 執行層 | `<service-or-runtime>` | 負責套用定義並產生行為 | 從 log、API 或畫面確認載入狀態 |
| 輸出層 | `<page-api-output>` | 讓學員觀察結果 | 對照設定、資料或程式來源 |

Step 銜接性檢查：每個 Step 必須能從上一個 Step 的完成狀態直接操作；會影響下一步的設定要標示保留、修改或刪除。Step 寫作順序：

1. 說明這一步改的是哪一層責任，以及為什麼要先做。
2. 提供操作步驟、指令或檔案內容。
3. 說明操作後會產生或修改什麼結果，以及如何支援下一步。

Step 不能只寫「建立檔案」、「貼上以下內容」、「執行指令」或「確認畫面」。要補上這個檔案、設定或資料如何被 runtime 讀取，以及為什麼後續畫面、API、log 或輸出結果會受到影響。

前置依賴與 Step 排序

撰寫或修改 Lab 時，先列出所有觀察與驗證動作，再反推所需依賴。任何「開啟頁面」、「查看 Console」、「執行查詢」、「驗證畫面」、「呼叫 API」之前，先確認環境、設定、資料、權限、程式、元件、API、套件、索引、endpoint、schema 或 policy 已建立、部署或啟用。若任一條件未成立，新增前置 Step，或把依賴建立動作移到更前面。課程順序固定為：建立或確認必要設定，建立或確認必要資料，再開啟頁面、Console、API 或查詢 URL 驗證。

其他文件結構

若課程來自學習清單或需求清單，README 必須保留主題覆蓋表：

主題覆蓋判斷：只有概念提到不算完整覆蓋；有操作步驟但沒有驗收方式算部分覆蓋；有操作步驟、練習題、確認方式與反查要求才算完整覆蓋。

課程主題切分與索引同步

課程文件依相似主題分組。一份 Lab 聚焦同一個學習目標或同一層責任，例如環境啟動與健康檢查、UI 操作與內容建立、Template 或 schema 設定、Component 與 Dialog、前端資源與資料模型、API 與查詢、Headless 內容、Workflow 與權限治理。

拆分判斷：

新增、拆分、重新編號或刪除課程文件後，同步更新：

• README 課程路線。
• 速查表或主題對照表。
• 補充文件中的 Lab 編號引用。
• 任何舊檔名、舊標題連結與舊 Lab 編號。
• 若有 HTML、PDF 或其他輸出版本，需重新渲染並確認索引順序一致。

完成後搜尋舊檔名、舊標題與舊 Lab 編號，確認沒有殘留引用。

可貼上程式碼範例

凡是學員需要寫入檔案、貼進查詢工具、貼進設定檔，或直接執行的內容，都使用標示語言的 fenced code block，不用表格取代可複製內容。適用於 XML、JSON、YAML、properties、config、HTML、template、CSS、SCSS、JS、TS、Java、C#、Python、SQL、GraphQL、Query DSL、shell、PowerShell 與 CLI 指令。

每段可貼上內容使用這個順序：

1. 明確寫出目標檔案、貼上位置或執行位置。
2. 提供完整可貼上的 code block，並標示語言，例如 xml、html、css、java、graphql、powershell。
3. 在 code block 下方補上 需要理解的參數設定：，只解釋當下需要理解、容易填錯、後續步驟會引用，或 placeholder 需要替換的欄位。
4. know why 優先課程使用「參數、架構意義」表格說明關鍵參數如何影響定義層、資料層、執行層或輸出層。

需要理解的參數設定： 建議格式：

學員看到內容後需要自行組合成檔案，或內容會影響後續驗證、部署、畫面顯示、API 回應時，改成完整 code block。範例中的名稱、關鍵參數或 placeholder 會被後續步驟引用時，在參數說明中點出讀取時機、套用位置與可觀察結果。表格只用於概念比較、UI 表單填寫值與參數用途說明，不取代檔案內容。

寫作風格

• 全文使用繁體中文；技術術語、UI 名稱、參數、指令保留英文並加反引號。
• 語氣直接、精確，不堆理論；先建立架構模型，再操作驗證模型。
• 優先用正向、直接的敘述句建立概念，不用先提出錯誤假設再反駁的問答式語氣。
• 排錯內容可保留，但主要標題使用「排錯提示」、「狀態判斷」、「使用原則」。
• 保留必要錯誤碼與訊息特徵，排錯索引用「狀態或訊息特徵、背後原因、處理」格式。
• 後續步驟才會建立的畫面、資料、檔案或設定，必須標示出現時機。
• UI 路徑寫成 `Settings` > `Advanced`；指令與參數值加反引號。
• 補充文件引用使用相對路徑：延伸閱讀：[<標題>](supplement-<topic>.md)。

練習題先說明沿用或清除前題狀態，再列操作步驟、確認方式、可觀察結果與反查來源。確認方式需同時包含：從畫面、API、log 或輸出結果確認行為；到資料、設定、檔案或 runtime 狀態確認來源；說明結果是由哪個設定、資料或程式造成。

完成檢查要驗收「能解釋」，不只驗收「能操作」：能完成最小實作、說明定義層/資料層/執行層位置、解釋設定如何影響 runtime 行為，並能從輸出結果反查到來源。

句型改寫方向：

Mermaid 規則

• 使用 flowchart LR 或 flowchart TD。
• Node ID 只用英數與底線；Node label 必須加雙引號。
• Edge label 必須加雙引號；關係明顯時可省略。
• Mermaid 內不可用 \n，換行改用 <br>。
• 每行一個 Mermaid statement。

輸出前確認

• 基本結構：文件開頭有 目標： 與 預估時間：；Lab 有 你會做出什麼、先理解本 Lab 的架構關係、完成檢查、本 Lab 的學習重點回顧。
• 架構與 Step：已說明主題責任層、修改內容、資料流、Step 順序原因、runtime 影響、結果觀察與反查方式；沒有先使用尚未建立的頁面、API、資料、權限或使用者。
• 可貼上與驗收：需寫入、貼上或執行的內容已提供完整 code block；關鍵參數已說明架構意義；每個重要主題至少有可驗收練習題，並要求學員從結果反查來源。
• 課程一致性：不相似主題沒有放在同一份 Lab；README、速查表、補充文件引用與實際檔案一致；若有 HTML、PDF 或其他輸出版本，已重新渲染並確認索引順序一致，且無舊檔名、舊 Lab 編號或舊標題殘留。
• 文字與位置：主要章節已避免「常見問題」、「常見錯誤」、「常見誤解」與反駁式句型；排錯索引用「狀態或訊息特徵、背後原因、處理」；教學內容放 docs/，可執行資產與環境入口放 repo 根目錄或根目錄功能資料夾。