類別 1：寫作與溝通 5 / 6
初階 Guide 5 Writing Documentation Technical

技術文件撰寫

用 Claude 撰寫清晰完整的技術文件 — 從 API 文件到使用手冊和 README。

2026年3月25日 10 min read

你將學到什麼

  • 如何使用 Claude 從程式碼、規格或粗略筆記中產出高品質的技術文件
  • 針對不同讀者受眾校準技術深度的技巧
  • 如何在大型文件專案中維持一致性和結構

使用情境

技術文件是軟體開發中最普遍被忽視的部分之一。每個人都知道好的文件很重要——它減少支援負擔、加速入門，並讓開源項目真正可用。但文件也很難寫好，容易被降低優先順序，並且隨著程式碼演進而痛苦地維護。

Claude 特別適合做文件工作，因為它能閱讀程式碼並理解其功能、將技術概念翻譯成平易近人的語言，並按需產生具有一致格式的結構化散文。以前害怕寫文件的開發者現在可以在幾分鐘內從程式碼庫中產出第一版草稿，並將精力集中在人類判斷上：包含什麼、什麼程度的細節是合適的、哪些例子真正有幫助。

本指南重點介紹三種常見的文件情境：README（任何項目的入口）、API 參考文件（公開介面的逐函數覆蓋），以及使用者手冊（面向終端使用者的任務導向逐步說明）。這些技巧也可以轉用到其他格式——教學、操作手冊、架構決策記錄——只需做小幅調整。

逐步指南

第一步：定義你的文件受眾和目的

在給 Claude 任何要記錄的程式碼或內容之前，要精確地確定兩件事：

讀者是誰？ 選項差異很大：第一次評估你的函式庫的開發者、正在入門現有程式碼庫的團隊成員、試圖完成任務的非技術使用者，或正在查找特定參數的有經驗使用者。每個受眾需要不同程度的解釋、不同的假設知識和不同的側重點。

讀者試圖做什麼？ 文件服務於特定的工作：「評估是否要使用這個函式庫」、「第一次安裝和運行」、「查找特定函數的行為」或「排除某些不工作的原因」。圍繞讀者的工作而不是你的程式碼結構來組織文件。

明確地給 Claude 這個背景資訊。這會改變輸出的一切。

第二步：給 Claude 提供原始素材

Claude 可以處理幾種類型的原始素材：

  • 直接的程式碼 — 貼上一個函數、類別、模組或整個文件。Claude 可以閱讀程式碼並推斷行為、參數、返回值和潛在的邊界情況。
  • 現有的粗略文件 — 貼上你的筆記、草稿或甚至程式碼中的注釋。Claude 可以擴展、重組和潤飾。
  • 口頭描述 — 用平易近人的語言描述系統的功能。Claude 可以產出一個文件骨架，你再填入具體內容。
  • 規格或需求 — 貼上設計文件或規格。Claude 可以產出與該規格一致的文件。

對於複雜的 API，每次處理一個端點或函數，而不是一次傾倒所有內容。這能產出更準確、更專注的文件。

第三步：指定文件格式

不同的文件類型有既定的慣例。告訴 Claude 要遵循哪種格式：

  • README：標準章節——功能說明、為什麼有用、安裝、快速開始、配置、貢獻、授權。
  • API 參考：每個端點/函數一個章節——描述、參數（名稱、類型、必填/可選、描述）、返回值、請求/回應範例、錯誤代碼。
  • 使用者手冊：任務導向——編號步驟、警告和注意事項的標注、方括號中描述的截圖（你之後添加真實截圖）、每個步驟的預期結果。
  • 概念概述：以為什麼為重點——正在解決的問題、思維模型、各部分如何配合，以及何時使用這個而不是替代方案。

第四步：在技術準確性和清晰度上迭代

Claude 的第一版草稿在結構上會很好，但可能包含技術不準確之處——尤其是當它從程式碼推斷行為而不是實際運行時。審閱每一個技術聲明：

  • 參數名稱和類型正確嗎？
  • 所描述的行為是程式碼實際做的嗎？
  • 錯誤代碼和錯誤訊息準確嗎？
  • 例子實際上可以運行嗎？

具體地修正錯誤：「timeout 參數是可選的，預設為 30 秒，而不是必填的。請修正這一點並更新例子。」

同時從讀者的角度審閱清晰度：「第 2 步中的身份驗證解釋假設讀者已經有 API 金鑰。添加一個說明如何獲取金鑰的注意事項。」

第五步：生成例子和程式碼範例

好的文件靠例子維生。永遠單獨請求程式碼範例，並比散文更加重視它們：

「對於這個 API 參考中的每個函數，生成一個完整、可運行的 Python 程式碼範例。例子應該展示最常見的真實世界使用案例，而不是最小的玩具例子。包含 import 語句和任何必要的設置。」

程式碼範例應該是複製粘貼即可使用的。如果它們需要替換真實值（如 API 金鑰），使用清晰標記的佔位符：YOUR_API_KEY_HERE 而不是 key123。

提示範本

我需要撰寫技術文件。以下是背景資訊：

**文件類型**：[README / API 參考 / 使用者手冊 / 教學 / 操作手冊]
**項目名稱**：[項目或工具的名稱]
**功能說明**：[1–2 句話的描述]
**目標讀者**：[誰在閱讀這個？他們的技術程度和職位是什麼？]
**讀者的工作**：[讀者試圖用這份文件完成什麼？]
**格式慣例**：[任何要遵循的特定格式，例如「OpenAPI 風格」或「Stripe 風格 API 文件」]

請為以下原始素材產出文件：

---
[在此貼上你的程式碼 / 規格 / 粗略筆記]
---

對於每個章節：
- 為第一次接觸這個內容的人寫作
- 用 [VERIFY] 標記任何你不確定行為的地方
- 每個主要概念至少包含一個程式碼範例
- 將技術術語保持在這個受眾所必需的最低限度

技巧與最佳實踐

  1. 貼上真實程式碼，而不是偽代碼 — Claude 從實際程式碼中產出的文件比從程式碼描述中產出的要準確得多。不要解釋你的函數做什麼——貼上函數。Claude 直接閱讀程式碼的準確率遠高於從描述中發明準確細節。

  2. 請 Claude 標記自己的不確定之處 — 在每個文件提示中添加這個：「如果你在推斷行為而不是直接從程式碼中讀取，請用 [INFERRED] 標記該部分。我在發布前會驗證這些。」這可以防止聽起來有信心但實際上錯誤的文件。

  3. 記錄「為什麼」，而不只是「是什麼」 — 程式碼解釋發生什麼。文件應該解釋為什麼：為什麼做出這個設計選擇、為什麼你會使用這個函數而不是替代方案、為什麼這個參數存在。定期請 Claude：「對於這個 API 中的每個主要設計決策，添加一個簡短的『為什麼這樣設計』的注意事項。」

  4. 保留文件風格指南提示 — 如果你在記錄一個大型項目，一致性很重要。定義一次你的慣例（如何命名事物、是否使用第二人稱或第三人稱、如何格式化警告和注意事項），並在每個文件工作階段開始時貼上這個風格指南。

  5. 使用 Claude 審核現有文件 — 給 Claude 你現有的文件並問：「一個新開發者在閱讀這個後會有哪些問題沒有得到解答？什麼不清楚？缺少什麼？」這比你自己重新閱讀文件更快地產出一個有針對性的差距清單。

動手試試

找一個你寫過但沒有文件的函數、模組或腳本。可以是個人項目、工具腳本，或你工作程式碼庫中的某個東西。

將程式碼貼入 Claude，使用上面的提示範本，將讀者設定為「從未見過這個程式碼庫的開發者」，並請求 README 或函數級別的文件。

審閱輸出中的任何技術不準確之處（可能會有一兩個——在對話中修正它們），然後用新鮮的眼光看看結果：這是你第一次遇到這樣的函式庫時希望存在的文件嗎？如果不是，告訴 Claude 缺少什麼。你會比你想象的更快達到那個標準。