technical-writing | 寫出能照做的操作文件
本頁以 pstack-claude 0.9.126 為基準。我們用一個已提供指令的靜態網站專案，寫出從啟動到預覽的教學草稿。重點是讓第一次操作的人知道每一步完成後要看什麼，不是替專案發明新指令。
定位與適用情境
technical-writing 將文件目的、句子寫法、指令拆分與語意清楚程度分層處理。第一層使用 Diátaxis 文件分類法，區分教學、操作指南、參考與解釋。一份文件先選一種模式，不把所有背景資料塞進操作流程。
另外三層採用 Google 開發者文件風格、簡化技術英文（STE）與全球英文（Global English）的規則。本例將這些要求落實為主動語態、單一操作與指涉清楚的句子。
本例採用教學（tutorial）模式，讀者跟著步驟完成第一次預覽。若讀者只想查旗標，應另寫參考（reference）文件，而不是讓本篇教學同時充當完整指令表。
準備
準備一份已確認的專案指令清單。以下條件只作為本練習的輸入。
- 工作目錄是
techspecs-web/，相依套件已安裝。 pnpm run dev啟動開發伺服器，預設網址為http://localhost:4321。pnpm run build產生靜態檔案與 Pagefind 搜尋索引。pnpm run preview預覽建置結果。預覽網址以終端實際輸出為準。
若代理能讀取目標專案，先要求它核對 package.json 與專案文件。若只能取得這份清單，讓代理標示尚未實測，不把預設網址寫成實際觀測結果。
操作步驟
- 指定讀者要完成的成果。本例是在瀏覽器看見開發頁面與建置後的頁面，文件模式選教學。
- 交付準備資料，要求代理先列步驟骨架。每一步只包含一個操作，並附上讀者要觀察的結果。
- 要求代理完成草稿。把啟動指令、瀏覽器檢查、停止伺服器與建置拆開，不用一個長句交代所有操作。
- 依草稿在獲准的環境試走。將實際終端訊息與頁面狀態回填，修正錯誤假設。未執行的步驟保留「預期」標示。
- 用
unslop規則檢查措辭。保留實際指令與路徑，刪除「輕鬆啟動」或「打造無縫體驗」這類不交代操作的句子。
可直接使用的提示詞
用 pstack:technical-writing 寫一篇第一次預覽靜態網站的教學。
只在回覆中交付草稿，不執行指令、不修改檔案。
採用 Diátaxis 的 tutorial 模式，不混入完整指令參考或架構解釋。
練習輸入：
讀者已在 techspecs-web/，且已安裝相依套件。
pnpm run dev 啟動開發伺服器，預設網址是 http://localhost:4321。
pnpm run build 產生靜態檔案與 Pagefind 搜尋索引。
pnpm run preview 預覽建置結果，網址須讀取終端輸出。
開頭直接說明讀者會完成的成果。
每一步只要求一個操作，附上可觀察的預期結果。
說明何時停止前景伺服器，再執行下一個指令。
未知的終端輸出與產物路徑不要補造。
保留指令、目錄與 Pagefind 名稱，首次出現的技術詞中英並列。
依 unslop 規則檢查草稿，最後列出尚未實測的部分。預期結果與驗收
預期草稿先讓讀者啟動開發伺服器，再用終端顯示的網址開啟頁面。停止伺服器後才進入建置與預覽。預覽也使用終端顯示的網址，不臆測它與開發伺服器相同。
逐步檢查下列條件。
- 每個指令都有執行目錄或明確沿用的目錄。
- 命令與網址符合輸入，沒有自行新增旗標。
- 每一步都有看得到的結果，例如終端顯示網址、瀏覽器呈現頁面或建置程序成功結束。
- 文件分清預期結果與實測結果，不把草稿當成成功紀錄。
- 讀者不必離開步驟，先讀完一段架構歷史才能繼續。
限制與權限
技能提供寫作標準，不替代專案測試。句子清楚不代表指令在任何環境都能執行。遇到未知版本、工作目錄或輸出，先取得證據。
原文也適用於設計提案、README、合併請求（PR）描述與提交訊息，但不把產品介面文案當成技術文件。本例只產出教學草稿。實際建置、寫檔、提交或發布仍受專案權限約束。