AO2 FIELD GUIDE · N032 · 內容策略與專業表達
技術術語白話解釋先回答讀者要做的判斷，再用日常比喻連回真正機制、規格及限制。附術語解釋卡與理解測試，不用刪掉條件換取好懂，也不把熟悉的例子當成技術證據。
把 API 換成「系統溝通的橋樑」，讀者可能點頭，仍不知道要提供什麼、失敗會怎樣。好的白話不是把名詞換成另一個形容詞，而是讓讀者能解釋機制，並做出下一個判斷。
技術術語白話解釋，先選讀者需要知道的那一層
同一個 API，主管可能要判斷能否與既有系統配合，工程師則要看認證、請求格式及錯誤回應。先寫角色和任務，再決定第一段保留哪些概念。必要名詞第一次出現時給簡短定義，後續保持同一名稱，不為避免重複而換成三個近義詞。
GOV.UK 的清楚用語指引支持以讀者可理解的文字處理專業內容；它不是要求把所有細節刪光。把正文分成「先懂用途」「再看條件」「需要時查細節」三層，能讓不同讀者停在適合的位置。白話要降低理解門檻，不能降低事實標準。
白話例子：API 像櫃台，還要說清楚櫃台能辦什麼
假想團隊用櫃台解釋 API：你按規定格式提出申請，櫃台核對身分和資料，再按規則回應。這比「兩套系統無縫對接」多交代了輸入、權限與回應。接著仍要說明可用的操作、必要欄位與不接受的情況，不能停在比喻。
申請表對應請求資料，身分核對是認證或授權的一部分，回覆則對應狀態與內容。但 API 不一定像人工櫃台同步完成全部工作，也不必然使用某種協定；非同步處理、重試與速率限制要依實際接口另說。這個比喻只建立理解入口，不是系統設計規格。
用一張解釋卡，把例子拉回實際機制
解釋卡至少包含原名、在本情境的定義、讀者問題、比喻、真實對照、失效邊界與核准來源。先讓編輯填，再由專業角色確認對照是否成立。比喻越生動，越要檢查會不會暗示資料必然即時、永不遺失或任何系統都能使用。
例如把快取說成「桌上的便條」後，要補它存的是哪些資料、何時更新，以及讀者可能看到舊值的條件。若無法回答，問題可能是資料缺失，不能靠比喻補足。術語表負責名稱一致；解釋卡負責在特定任務中教會判斷，兩者可以互連而不重寫一套字典。
| 欄位 | API 假想示例 | 核對問題 |
|---|---|---|
| 用途 | 依指定操作交換資料 | 讀者接下來要做什麼 |
| 比喻 | 有規則的服務櫃台 | 哪些對照成立 |
| 機制 | 請求、權限、回應及處理狀態 | 是否使用實際接口文件 |
| 限制 | 不保證即時或全功能相容 | 容易多想出哪種承諾 |
先寫可採取的行動，再決定要留哪些數字
需要比較規格時，把單位、量測方法、適用版本與限制放在數字附近。沒有相同基準，不用「更快」代替比較；讀者不需要每個公式，也仍須知道這個數值能不能拿來選型。短句可以拆開，但不要把「在指定條件下」拆到很遠的頁尾。
一個可用寫法是「先提供目標系統版本與需交換的欄位，再核對接口是否涵蓋；未確認前只能評估，不能承諾整合」。這句讓採購知道下一步，也保留技術判斷。一般介紹、規格表與接口文件各有用途，連結應告訴讀者點開後能核對哪個條件。
用重述與反例檢查理解，不只問有沒有看懂
請目標讀者用自己的話說出用途，再判斷一個適用例子和一個不適用例子。像「接口存在，是否代表所有資料都能交換？」若仍回答可以，表示權限、格式或範圍沒有講清楚。記下誤解，回到對應句子修改，再請專業角色確認沒有修過頭。
能照做，還能辨認何時不能照做，才算理解。驗收可觀察是否知道要準備哪些資料、在哪裡停下詢問，以及哪份正式文件能確認。內部同事已熟悉名詞，不能完全代替新讀者；也不要把一次成功重述當成所有人都理解的比例。
| 檢查方式 | 可觀察結果 | 需要修正的線索 |
|---|---|---|
| 用自己的話重述 | 說出用途及前提 | 只重複名詞 |
| 選適用情境 | 指出成立的條件 | 把示例當通用能力 |
| 判斷反例 | 知道哪裡需另確認 | 認為任何資料都可用 |
| 準備下一步 | 列出必要欄位與文件 | 仍不知道該提供什麼 |
比喻要能對照技術，也要知道在哪裡停止
白話例子先幫讀者理解關係，再逐項對回產品、資料與工作。可以說查詢展開像把採購大問題拆成幾份查證清單，但不能因此說所有平台每次都跑同一流程。比喻是理解工具，不是技術證據。
每個例子補三件事：對應什麼、哪些地方不能類推、讀者接下來做什麼。若刪掉比喻就沒有任何方法，表示文章還不夠完整；若比喻讓人誤以為已發生的客戶案例，應明確標成假想演練。
常見問題
用了比喻還需要寫正式名詞嗎？
通常需要，讓讀者能與文件、供應商和技術人員對話。第一次出現時連上白話定義，之後維持同一用詞，必要細節放到可辨認的連結。比喻不是新名稱，也不能代替正式規格；最後請讀者對照兩者，確認知道哪一段是理解工具、哪一段才是實際條件。
白話文章一定不能放數字與規格嗎？
可以放，重點是數字是否支援讀者的判斷。保留單位、方法、版本與限制，解釋數字改變時會影響什麼；不用把所有公式放在開頭。不同條件的值不能直接排成優劣。若資料不足，明說需要確認哪個欄位，不用一個看似簡單的平均值蓋過差異。
請 AI 改成小學生懂就夠嗎？
不夠，這種指令可能刪除重要條件，或產生熟悉但不準確的比喻。應先提供讀者角色、任務與核准來源，要求保留必要名詞、例外和未知，再由專業角色逐項核對。最後讓實際目標讀者重述與判斷反例，不能只靠語句順暢判定內容正確。
白話總結：讓人看懂，也知道哪裡要停下來確認
比喻像入口指標，帶人進來後還要交代真正的路線、限制與要準備的資料。
- 定問題：先寫讀者要做的判斷，選必要術語。
- 做對照：把例子逐項連回機制、正式來源與不成立的地方。
- 試理解：請讀者重述、判斷反例，再列出下一步資料。
完成條件：讀者能說出用途與限制，知道如何查證、何時需要請專業角色確認。
來源與方法範圍
資料查核：2026 年 10 月 24 日。來源支持文中對應的準則與平台說明；工作表、判斷步驟及已標示的假想情境由 AO2 整理，實際使用時依產品資料與現行設定核對。
