論述基礎與限制

本卡抽自 infra 接手維運模組的兩次使用者反饋。第一次：文章寫「拍下現況」「建立本地環境」，使用者問「用什麼拍？非 Docker 怎麼做？」——補了 FTP client、本地環境工具選型表、備份自動化指令。第二次：文章寫「拍下完整現況（不動 prod）」，使用者問「如果不是在 container 上運作，怎麼取代拍下來的動作？」——補了 phpinfo 擷取、cron 記錄、AMI 快照、系統軟體清單。兩次反饋的根因相同。限制：evidence 來自單一教學模組。

核心原則

操作型教材的一個動作（「拍下現況」「匯出資料庫」「建立備份」）在不同執行環境裡對應完全不同的工具路徑：

只寫動作不寫工具路徑，等於把「選工具」的認知負擔轉嫁給讀者。讀者知道該做「拍下現況」，但坐在電腦前不知道該打開什麼軟體。

情境

infra 接手維運模組的文章經過三輪多輪審查（compliance / cadence / steelman），所有 reviewer 都判定操作步驟邏輯正確、順序合理。使用者兩次指出同一個缺口：

第一次：「用什麼拍？怎麼拍？非 Docker 的環境怎麼做？」——三篇文章各補了 15-20 個工具提及，總修改量 138 行。

第二次：「如果不是在 container 上運作，怎麼取代拍下來的動作？」——兩篇文章各補了環境設定的拍照方法（phpinfo、cron、SSL、AMI 快照、系統套件清單），總修改量 87 行。

兩次的操作步驟在邏輯層都通過了 fact-check（「拍下現況」這個動作描述正確）和 steelman（「先拍後改」的順序合理）。問題出在「正確」跟「可執行」之間的落差——動作正確不代表讀者能執行，執行需要知道用什麼工具、在什麼環境限制下、有什麼替代方案。

理想做法

操作型教材的每一步至少帶一條環境專屬的工具路徑。如果教材涵蓋多種環境（container / VM / 共享主機），每一步要按環境分列工具，或明確標示「本篇的工具路徑適用於 X 環境、Y 環境的做法見另一篇」。

寫操作步驟時的自測問題：「讀者坐在電腦前、打開這篇文章，下一個動作是啟動什麼軟體或輸入什麼指令？」如果答案是「看情況」，就要把「情況」展開成環境分支。

生成端的檢查清單（寫完每一步後問）：

• 這一步的工具是什麼？有沒有寫出來？
• 這個工具在目標環境可用嗎？（共享主機沒有 SSH、沒有 CLI）
• 如果不可用，替代工具是什麼？
• 工具的操作有沒有環境限制？（phpMyAdmin 的 timeout、FTP 的非原子上傳）

沒這樣做的麻煩

• 兩次同根因的返工：同一個缺口（動作缺工具）被使用者指出兩次、修了兩輪，因為第一輪只補了「用什麼工具」沒補「在不同環境怎麼替代」。如果第一次就按環境分列工具路徑，第二次不會發生。
• 審查結構性盲區：fact-check 驗「正確性」、steelman 驗「完整性」，兩者都不驗「可執行性」。操作型文章的品質門檻比概念型文章多一層——除了正確和完整，還要可執行。這層門檻需要 executable-walkthrough frame（見outside-in reader frames report）。

判讀徵兆

操作型文章裡出現以下動詞但沒有跟著工具名稱或指令，就是候選缺口：

「拍下」「匯出」「備份」「部署」「掃描」「盤點」「監控」「還原」

這些動詞描述的都是需要工具才能完成的操作。概念型文章用這些動詞是在描述能力（「IaC 的責任是讓環境可重建」），操作型文章用這些動詞是在指引行動——行動需要工具。

跟其他抽象層原則的關係

• → 多輪審查缺 outside-in 讀者 frame：本卡是該卡盲點四（操作步驟缺工具指引）的具體展開，補充了「為什麼同根因會被指出兩次」的機制
• → 技術教材要內嵌管理層可彙報的資訊：工具路徑跟管理層資訊是同一類缺口——都是「讀者的下游任務需要但文章沒給的素材」
• → 讀者是缺經驗的專業人士、不是外行人：專業人士缺的不是概念（「要備份」），而是特定環境下的操作經驗（「共享主機沒有 mysqldump 時怎麼備份」）