newbie-handbook

# newbie-handbook · 非技術讀者的圖文教學手冊產生器 這個 skill 的定位是**不懂技術的使用者與 AI／技術架構之間的翻譯橋樑**：把任何「從準備到完成」的流程，翻譯成非技術讀者能邊看邊操作的 A4 直式 PDF。成品保持中立——不主動加入作者、個人品牌、社群帳號或導流內容。 讀者一律設定成**聰明但沒耐心的高中生**：學東西很快，但沒有任何技術背景，也沒耐心看鋪陳。 ## 規則放在哪裡 五組核心規則寫在同資料夾的 `references/`，本檔只留流程與差異段，不重抄條文： | 檔案 | 管什麼 | |---|---| | `references/grilling.md` | 動筆前的前置提問三題、複述鎖定、跳過判準、追問樹（含版本不影響操作時不追問）、非互動環境 fallback、外部條件檢查、執行細節（含各平台介面語言） | | `references/writing-eli5-cba.md` | 結論先行（手冊層＋步驟頁層）、專有名詞白話翻譯、生活化比喻判準、規則疊加順序、官方沒寫清楚的事實怎麼寫、三輪自檢（含真實截圖元素對照） | | `references/microsteps.md` | 微步驟粒度 14 條：一步一動作（含一步怎麼算）、成功畫面、卡關出口（含找人求助時的寫法）、checkpoint、分組門檻、附註層數 | | `references/deai-teaching.md` | 教學情境去 AI 味禁用清單 24 條（含正反例）、朗讀測試、假陽性白名單（含無法確認時保留的限定詞） | | `references/real-screenshots.md` | 畫面來源四層優先序、Playwright 實拍公開網頁的做法與最小腳本、繁中介面字樣查核（含機器翻譯頁判斷、逐字搜尋方法、站內全文搜尋、一般詞加引號計數、雙候選依更新日期排序、位置待核對）、登入牆／原生 App／版權／個資遮罩四條邊界（含登入牆兩階段：草稿版→正式版） | **路徑解析規則**：只解析相對於本 skill 資料夾的 `references/`。找不到這些檔案時停下來提示使用者確認資料夾有沒有完整複製，不要用檔名做全域搜尋當退路，也不要憑記憶把規則補完。 ## 必須交付 - A4 直式 PDF：向量文字、可列印。 - 可編輯的 HTML 原稿。 - 每個實際操作步驟至少一張真實截圖或 CSS 介面示意。 - 逐頁 QA 後的乾淨交付物；刪除 `qa-page-*.png`。 預設頁序： 1. 封面：主標、對象、一句話說明；不放署名或連結。 2. 總覽：先講做完會得到什麼、幾步、最容易卡哪裡；再用生活比喻講概念與 3–5 步驟總覽。 3. 事前準備：檢查清單，標出最容易卡住的一項。 4. 步驟 1…N：每步一頁，第一句先講這步要達成什麼，再明寫位置、按鈕、輸入內容與成功畫面，頁尾附卡關出口。 5. 疑難排解：常見卡關、求助時要提供的截圖與資訊。**固定包含一條「沒有錯誤訊息、只是沒反應」**：按了沒動靜、畫面一片空白或一直轉圈、找不到任何錯誤代碼時，先檢查哪幾件事（照這個主題寫具體，例如漏勾的勾選框、沒填的必填欄、被擋住的彈出視窗），還是不行怎麼求助（截圖時註明「畫面上沒有錯誤訊息」，附卡在第幾步）。2026 年 9 月第三次新手實測的疑難排解頁只列了有英文錯誤代碼的狀況，扮新手的測試指出畫面空白或轉圈時沒有對應的一條，只能直接跳到最後的求助法則。 6. 結尾：完成提示、下一步與檢查清單；不放 CTA、帳號或外部連結。 ## 鐵律 1. **以完全不懂的小白為讀者。** 不假設背景知識；專有名詞先用一句白話翻譯。明寫「在哪裡操作、點哪個按鈕、輸入到哪個框、看到什麼代表成功」。細則見 `references/writing-eli5-cba.md` 與 `references/microsteps.md`。 2. **動筆前先跑 Grilling 三題。** 三題拋出後停下來，等使用者回覆才動筆，收到回答先複述鎖定再規劃架構。瑣碎任務可跳過（判準四條寫在 `references/grilling.md`）；非互動環境有 fallback，但公開發布用途不適用。 3. **每個步驟都要有畫面，來源照四層優先序挑。** 使用者提供真圖 > Playwright 實拍公開網頁 > 官方文件圖（標註出處）> CSS 介面示意（誠實標示）。掉到最後一層才用 `assets/template.html` 的 `.win`、`.term`、卡片與對話泡泡畫 CSS mock。四層各自的做法、Playwright 最小截圖腳本，以及登入牆／原生 App／版權／個資遮罩四條邊界，見 `references/real-screenshots.md`。 4. **不可把 mock 說成真截圖。** 圖說標示「介面示意」；交付時說明哪些是真圖、哪些是示意。 5. **先查官方資料。** 版本、網址、指令、系統需求、登入方式與按鈕名稱先對照官方文件；不要靠記憶補完。 6. **禁止自我宣傳。** 封面、頁尾、結尾與裝飾區不得出現個人姓名、社群帳號、個人網站、QR code、追蹤提示、訂閱提示或行銷導流連結。 7. **成品一律不附網址或超連結。** 官方網址只用於研究與事實查核，不寫進 HTML、PDF 或交付文案。需要引導讀者時，改寫成選單路徑、搜尋詞或官方來源名稱；只有使用者在該次任務明確要求加入某個連結時才可例外。**改寫成搜尋詞或選單路徑的那一步，要多補一個卡關出口**：搜出來不只一條、或根本找不到的時候，讀者要靠哪個特徵認出正確的那一個（網站名稱、圖示長相、排在第幾條）。少了這個出口，等於把一步到位的網址換成一個沒人接住的新岔路。**例外：讀者要輸入或比對的網址是資料，不是連結。** 例如要貼進後台的回呼網址、要核對的網域，可以用純文字印出來（放進可照抄的框裡，不做成可點連結、不加 `href`），讓讀者有東西可以逐字比對。導流、社群、行銷用途的連結不在這個例外裡，照舊全面禁止。 8. **不要擅自加入品牌。** 只有使用者明確要求時，才加入其公司名稱、Logo 或內部聯絡資訊；仍不加入任何未要求的外部導流。 9. **配色固定。** 使用模板 CSS tokens：`--bg #FAF9F5`、`--bg-warm #F3ECE0`、`--card #FFFDF8`、`--orange #D97757`、`--orange-deep #BE5C39`、`--orange-soft #F8E6DA`、`--ink #26241F`、`--green #5E8B6A`。 10. **交付前跑去 AI 味三輪掃。** 照 `references/deai-teaching.md` 的分輪順序掃過，每一條命中都要貼得出原文句子；同時守假陽性白名單，不要把步驟編號、正式語域、簡短指令句誤判成 AI 味。全文一律台灣用語、零簡體字。 ## 工作流程 ### 1. Grilling 前置提問 照 `references/grilling.md` 問三題並等回覆、複述鎖定。符合跳過判準才直接進第 2 步。 ### 2. 執行細節釐清 確認作業系統（版本不影響操作就不追問）、每個會操作到的平台各自的介面語言、輸出位置、是否有現成截圖，以及是否要加入使用者自己的公司名稱或內部聯絡方式。細則見 `references/grilling.md`「三題之後：執行細節釐清」。未指定輸出位置時，在目前工作區建立「<主題> 手冊」資料夾；不要自行寫入廣泛目錄。 ### 3. 查核 涉及具體產品或工具時，查官方安裝與使用文件，記下： - 正式產品名稱與目前介面名稱。 - 安裝與登入網址、系統需求。 - 指令、路徑、權限與前置條件。 - 介面可能因版本或帳戶不同而改變的地方。 ### 4. 建立專案 從本 skill 複製： ```bash cp assets/template.html <專案資料夾>/index.html cp assets/render.mjs <專案資料夾>/render.mjs ``` 使用實際 skill 目錄解析相對路徑；不要假設目前工作目錄就是 skill 目錄。 ### 5. 填內容與畫面 - 將模板 `【…】` 佔位完整換成真內容。 - 依流程複製 STEP 頁；同步總覽步驟與頁碼。 - 照 `references/` 的寫作規範與微步驟規則寫：每頁結論先行、一步一動作、明寫成功畫面、頁尾附卡關出口。 - 優先排序讀者在真實情境下最自然、最完整的主路；替代方案再放後面。 - 真實截圖使用 `<img>`；CSS mock 清楚標示「介面示意」。 - 不在封面或結尾補上任何作者、社群或「更多教學」連結。 ### 6. 渲染 在專案資料夾執行： ```bash node render.mjs index.html "<主題> 手冊.pdf" ``` `render.mjs` 會嘗試載入本地或 global Playwright，輸出 PDF 與 `qa-page-NN.png`。若缺少 Playwright，告知使用者所需安裝步驟，不要偷偷改用低品質截圖拼 PDF。Playwright 自帶的瀏覽器不在時，它會自動改用電腦上的 Google Chrome；兩個都開不起來時會印一段白話說明，照那段說明轉告使用者。 ### 7. 逐頁視覺 QA 逐張打開所有 `qa-page-NN.png` 肉眼檢查： - 文字、圖片或頁碼是否被裁切。 - 卡片是否重疊或超出 A4。 - 是否有大片無意義留白或內容太擠。 - 真實截圖在列印尺寸下是否仍看得清楚。 - 封面、頁尾與結尾是否沒有個人署名、社群帳號、QR code 或導流 CTA。 - HTML 與 PDF 沒有可點連結（`href`）、QR code 與導流網址；有印出網址的地方，逐一確認它是讀者要輸入或比對的資料（鐵律 7 的例外）。 同一輪順便跑摩擦力自檢（`references/microsteps.md` 第 14 條）、真實截圖元素對照（`references/writing-eli5-cba.md` 格式輪）與去 AI 味三輪掃。有問題就修改 HTML、重渲染並重看受影響頁；成功 exit code 不能代替肉眼 QA。 ### 8. 清理與交付 - 刪除全部 `qa-page-*.png`。 - 回報 PDF 與 HTML 的完整路徑。 - 說明真實截圖與示意圖的使用範圍。 - 只要有步驟因為登入牆只能用示意圖，這一版就標「草稿版」交付，並明講「要有人拿真帳號照做一遍、換成真圖後才算正式版」，同時附上要截哪幾張圖的清單（兩階段做法見 `references/real-screenshots.md` 邊界 1）。 - 不在交付訊息追加 skill 未要求的宣傳連結。 ### 9. 回饋進版 下一版修訂優先處理「實測真的卡住人」的步驟——逐頁校稿判讀紀錄、讀者回報卡在第幾步——而不是憑寫手直覺猜哪一步難。沒有回饋資料時這一步跳過，不要編。 ## 設計與元件 完整 CSS 位於 `assets/template.html`： - `.page`：210×297mm A4 頁。 - `.kicker`、`h2.title`、`p.lead`：資訊層級。 - `.card`、`.warm`、`.tint`、`.chip`、`.tag`：卡片與標籤。 - `.stepnum`：步驟圓標。 - `.win`、`.win-bar`、`.term`：瀏覽器、App、Finder、終端機 mock。 - `.shot`、`.mark`、`.cap`：真實截圖版位、圖上橘色記號、圖說（規則見 `references/real-screenshots.md`）。 - `.ok`、`.exit`、`.fill`：成功畫面框、卡關出口框、內容撐版容器。 - `.pg-foot`：中立頁尾，只放手冊名、章節或頁碼。 ## 常見調整 - 多步驟：複製 STEP `<section class="page">`，修改編號與頁尾。 - Windows：用橘色左框標示 Windows 專屬步驟。 - 真截圖：將 mock 換成 `<img>`，圖片存於專案 `assets/`。 - 使用者品牌：只有明確要求時才加入其 Logo 或公司名；不推定授權。 ## 避免主次顛倒 方法排序要符合讀者當下真正會使用的主路。不要因為抽象的風險感，把已登入、已安裝、最完整的正常操作縮成角落註解；先釐清真實風險邊界，再用適當護欄呈現主路。主路放前面、字級與畫面給足，替代與進階選項再往後放。 讀者看完覺得「這一步怪怪的」，通常不是內容錯，是主次擺錯。 ## Bundled assets - `assets/template.html`：無署名、無社群、無結尾導流的 A4 六頁骨架。 - `assets/render.mjs`：HTML → A4 PDF＋逐頁 QA 截圖。