Google 技術文件怎麼寫？讓讀者完成任務的文件方法

類型	讀者要做什麼
Tutorial	跟著做一次，邊做邊學
How-to	完成一個明確任務
Concept	理解原理、名詞與關係
Reference	快速查參數、方法、選項或規格
README	快速理解專案、安裝並找到下一步文件

這些類型可以互相連結，但不要全部混在同一段。

例如「OAuth 怎麼運作」和「如何設定 OAuth」最好分開。前者是理解概念，後者是完成任務；如果交錯寫，熟手嫌太慢，新手又會在步驟中迷路。

技術文件不是產品功能清單

產品團隊很容易照功能架構寫文件：帳號模組、權限模組、通知模組、付款模組。

讀者通常帶著具體任務進來，例如「如何新增管理員」「為什麼付款失敗」「如何取得 API Key」，很少是為了研究產品內部的模組劃分。

所以文件架構要盡量靠近讀者任務，而不是內部組織方式。

第二人稱比「使用者」更直接

Google 的文件風格偏好直接對讀者說 you。中文也可以採同樣思路。

例如「完成設定後，你可以重新整理頁面」會比「使用者完成設定後可重新整理頁面」更直接。

技術文件不需要一直稱呼「使用者」。當文件本來就是寫給正在操作的人，直接說「你」通常更清楚。

主動語態讓人知道誰要做什麼

被動語態最大的問題，是很容易把責任藏掉。

例如「設定必須被儲存」不如「按一下儲存」直接。

程序文件尤其適合使用主動語態與命令句：

開啟設定。
選取網域。
輸入你的網域名稱。
按一下儲存。

讀者不用先分析句子，就知道下一步要做什麼。

條件要放在動作前面

如果一個步驟只適用特定情況，先講條件，再講動作。

如果你的網站使用自訂網域，請先完成 DNS 驗證。

會比「先完成 DNS 驗證，如果你使用自訂網域」更安全，因為讀者在動手前就知道這一步是否適用自己。

Procedure：一個步驟只放一個主要動作

程序最怕把五件事塞成一個長句。

如果讀者需要依順序完成工作，就使用編號步驟；每個步驟只保留一個主要動作，必要時再加結果。

按一下部署。狀態變成「部署中」。
等待狀態變成「完成」。
開啟產生的網址。
確認首頁正常顯示。

最後的確認很重要。文件不能只告訴讀者做什麼，也要告訴他怎麼知道自己做對了。

每個 Procedure 最後都要有 Verify

「按完按鈕」不代表任務完成。好的 Procedure 應該告訴讀者，成功時會看到什麼。

例如不要只寫「按一下儲存」，還可以補一句：「確認頁面顯示『設定已儲存』。」如果成功後還有下一個常見任務，再提供清楚的 What’s next，讓讀者知道接下來去哪一頁。

這樣文件會形成一個有起點、完成條件與下一步的任務流程，不會只剩一串動作。

Before you begin 要放在第一步之前

如果一個流程需要帳號權限、API Key、特定版本或已完成的設定，應該在開始前一次列清楚。

不要等到第 4 步才突然說：「你必須先擁有管理員權限。」這會讓讀者前面做的工作全部中斷。

Heading 要像目錄一樣能被掃讀

多數人不會從技術文件第一個字讀到最後一個字，而是先掃標題找自己需要的段落。

任務型標題可以直接寫「安裝外掛」「設定 API Key」「驗證網域」；概念型標題則可以寫「權限模型」「付款狀態」「快取生命週期」。

如果一份文件只看到「介紹」「更多說明」「進階內容」，讀者很難靠目錄找到答案。

列表、表格與 Notice 都要有明確工作

列表適合平行項目；有順序才使用編號。表格適合比較固定欄位，但要有標題列，而且不要把重要操作藏在過度複雜的表格裡。

Notice 也不要濫用：

Note：有幫助，但不是完成任務必須知道。
Caution：操作前要小心，可能造成不良結果。
Warning：可能造成嚴重或不可逆影響。

如果每一段都是「注意」「重要」「警告」，最後等於沒有任何一段真的重要。

Cross-reference 不要寫「上面」「下面」「點這裡」

文件會重新排版，也可能被翻譯、節錄或直接從搜尋結果跳進某個段落。像「請看上面」「更多資訊點這裡」這種寫法，離開原本畫面後就很難理解。

比較穩定的做法是直接說出目標，例如「請參閱『設定自訂網域』」；Link text 本身就應該告訴讀者會去哪裡，而不是依賴周圍句子補意思。

Code Sample 必須讓人知道怎麼改

程式碼範例不是放一段看起來像真的程式就完成。

好的 Code Sample 應該只保留完成任務需要的程式，在範例前先說明用途，Placeholder 要明確，範例後則解釋哪些值需要替換；如果可以執行，最好再附上預期結果。

例如不要用模糊的 <your-key> 混在指令裡，可以使用清楚的 API_KEY，並在下方說明要用自己的金鑰替換。

Reference 文件可以刻意公式化

教學文章需要流暢，Reference 則更重視完整與一致。

如果每一個 API Method 的說明格式都不同，查閱速度反而會變慢。

例如每個 Method 都固定說明用途、Parameters、Return Value、Errors／Exceptions 與 Example。這種重複結構能降低查找成本，刻意保持一致反而更適合 Reference 文件。

Documentation Map：先讓讀者知道下一份文件在哪裡

當文件變多之後，問題常常不在單頁寫得差，而是整套文件沒有地圖。

README 或 Getting Started 可以扮演入口，清楚告訴讀者第一次使用從哪裡開始、常見任務去哪裡找 How-to、原理去哪裡看 Concept、API 去哪裡查 Reference，以及錯誤去哪裡看 Troubleshooting。

這樣讀者不需要靠搜尋猜關鍵字，也能自己找到下一步。

Local Style Guide 要優先，避免整個專案出現兩套語言

如果團隊已經有自己的術語、命名、UI 文案與文件慣例，文件應該先維持專案內部一致，再參考 Google 的一般原則。

例如產品介面一直使用「登入」，文件卻突然改成另一個詞，讀者反而會困惑。

風格指南的目的，是讓同一套產品在不同頁面維持一致，讀起來像同一個團隊寫的，而不是拿來爭論哪一種寫法最標準。

事實正確，比文字漂亮更重要

技術文件最大的風險是教錯。句子再漂亮，只要 Command、Parameter 或實際行為錯誤，讀者就會被帶到錯的方向。

任何 Command、Flag、Parameter、Return Value、版本需求與實際行為，都應該回到程式碼、產品或可驗證來源確認。

如果一件事目前無法確認，寧可先標示待驗證，也不要靠印象補出一個看起來合理的答案。

這和Clean Code：好程式碼不是能跑就好，而是讓下一個人看得懂、改得動的精神很接近：可讀性很重要，但前提仍然是內容正確。

文件也會產生版本債，功能改了就要一起更新

技術文件最危險的狀態之一，是看起來很完整，內容卻已經過期；讀者往往會因為它看起來正式而更相信。

只要產品修改了參數、操作路徑、權限、預設值或錯誤訊息，就應該檢查受影響文件。重大版本變更則要搭配 Release Notes、Migration Guide 或 Changelog，告訴既有使用者什麼變了、要做什麼。

如果文件和產品更新是兩條完全分離的流程，文件失真幾乎只是時間問題。

文件要避免容易過期的時間詞

Google 的文件方法重視 timeless documentation（耐久文件）。

例如「新版介面現在提供這個功能」過幾個月後就會變得奇怪；如果功能已正式存在，直接描述目前行為通常更耐久。

同樣地，不要在正式文件預告尚未發布的功能，除非那份文件本身就是 Roadmap 或 Release Communication。

Accessibility 不是只有圖片加 alt

技術文件也需要無障礙設計。

連結文字本身能說明目的，不只寫「點這裡」。
圖片中的重要資訊要同步出現在文字中。
圖片有適合的替代文字。
表格有清楚 Header。
標題順序合理。
不要只靠顏色區分狀態。

讀者可能使用螢幕閱讀器，也可能從搜尋結果直接跳進文件中段。文件結構越清楚，越不需要依賴「你剛才應該已經看到上面那張圖」。

為全球讀者寫作，要減少模糊與文化假設

Google 的 Style Guide 也特別提醒全球讀者與翻譯情境。

技術文件應盡量避免俚語、雙關、文化限定的比喻，以及不必要的模糊詞。

「很簡單」「只要一下子」「大家都知道」這類句子沒有提供技術資訊，還可能讓卡住的讀者覺得問題出在自己。更好的寫法是直接說清楚動作、條件與結果。

發布前，用固定順序自我檢查

事實：Command、參數與產品行為都正確嗎？
讀者：這頁是寫給誰？任務清楚嗎？
結構：文件類型、Heading、Procedure、List 是否清楚？
語態：是否直接、主動、容易知道誰做什麼？
一致性：同一個名詞是否一直用同一個名稱？
Accessibility：Link、Image、Table、Heading 是否可用？
耐久性：是否有很快就會過期的時間詞？

先修結構，再修句子，最後才處理細小字詞，效率通常更高。

一張表判斷文件為什麼難用

症狀	優先檢查
讀者找不到要做的步驟	Audience、Task、Heading
新手看不懂，熟手嫌太長	文件類型是否混在一起
照步驟做還是失敗	Prerequisites、Fact Verification、Verification Step
一段話看很多次才懂	Active Voice、Sentence Length、Jargon
每頁同一概念叫不同名字	Terminology Consistency
程式碼看得懂卻不能直接用	Placeholder、Context、Expected Output
過半年文件就顯得過時	Timeless Writing、版本資訊

常見問題

技術文件是不是越完整越好？

不一定。完整不等於把所有資訊塞進同一頁。對讀者來說，更重要的是能快速找到和目前任務相關的資訊，再透過連結延伸到其他文件。

Tutorial 和 How-to 有什麼差別？

Tutorial 比較適合第一次學習，會帶讀者走完一條完整路徑；How-to 假設讀者已有部分背景，目標是完成一個明確任務。

技術文件一定要用第二人稱嗎？

操作型文件通常直接對讀者說「你」會更清楚，但仍要依語言與專案風格調整。最重要的是避免讓動作主體變得模糊。

文件裡可以寫「很簡單」「只要」嗎？

通常沒有必要。這些詞沒有增加操作資訊，也可能讓遇到問題的人覺得被責怪。直接寫出步驟與條件更精確。

程式碼範例一定要能執行嗎？

如果範例的用途是讓讀者跟著操作，應盡量做到最小、完整、可執行；如果只是片段示意，則要清楚標示上下文與需要替換的值。

README 要寫到多詳細？

README 的主要工作是讓讀者快速理解專案、開始使用並知道後續文件在哪裡。太深的 Concept、API Reference 或大型 Troubleshooting 可以拆到獨立文件。

好的技術文件，衡量標準是讀者有沒有完成任務

Google 技術文件方法最值得借用的，是一個清楚的處理順序，而不只是某一個標點或用字規則：先知道讀者要做什麼，再安排文件；先確認事實，再修文字；先把結構做清楚，再追求句子漂亮。

當 Audience、Task、Scope、Procedure、Code Sample、Verification 與 Accessibility 都被照顧到，文件就不只是「有人寫過」，而是可以降低支援成本、縮短學習時間，讓下一個人不必重新問一次。

技術文件寫得好，最理想的結果是讀者很快完成工作，然後離開文件繼續做事；文筆只是達成這個目的的工具。

參考資料

Google Developer Documentation Style Guide。
Google Technical Writing One。
Google Technical Writing Two。

Google 技術文件方法：好的文件不是寫很多，而是讓讀者完成任務

第一步：先定義 Reader 和 Task

文件開頭先說清楚範圍，也要說哪些內容不包含

不要把不同文件任務全部塞在同一頁