技術文件寫作
前言
你寫的文件有人看嗎？ 很多開發者覺得「程式碼能跑就行，文件以後再說」。結果就是：新人到職看不懂專案、API 對接全靠口頭溝通、半年後自己都忘了當初為什麼這麼設計。
本章帶你掌握技術文件寫作的核心方法，讓你的文件真正有人看、看得懂、用得上。
這篇文章會帶你學什麼？
| 章節 | 內容 | 核心概念 |
|---|---|---|
| 第 1 章 | 文件的類型與結構 | 不同文件的寫法 |
| 第 2 章 | 寫作原則 | 清晰、準確、簡潔 |
| 第 3 章 | 實戰對比 | 好文件 vs 差文件 |
| 第 4 章 | 文件維護 | 讓文件保持更新 |
學完本章，你將能寫出結構清晰、內容準確、易於維護的技術文件。
0. 全景圖：為什麼技術文件重要？
程式碼告訴電腦「怎麼做」，文件告訴人類「為什麼這麼做」。沒有文件的專案就像沒有說明書的電器——能用，但用起來全靠猜。
好文件的價值
- 降低溝通成本：新人自助上手，減少重複解答
- 保存決策上下文：記錄「為什麼」，而不只是「是什麼」
- 提升專案可信度：好文件是開源專案的門面
- 加速協作：API 文件讓前後端平行開發
1. 文件的類型與結構
透過下面的互動元件，了解不同類型文件的標準結構：
Documentation structure template - click to switch document types
1Project name + one-line description▶
2Quick start▶
3Features▶
4Usage examples▶
5Contributing + license▶
1.1 常見文件類型
| 文件類型 | 目標讀者 | 核心內容 |
|---|---|---|
| README | 所有人 | 專案是什麼、怎麼用、怎麼貢獻 |
| API 文件 | 介面呼叫方 | 端點、參數、回應、錯誤碼 |
| 架構文件 | 開發團隊 | 系統設計、技術選型、資料流 |
| 變更日誌 | 使用者/開發者 | 版本變化、新增/修復/破壞性變更 |
| 貢獻指南 | 貢獻者 | 開發環境、程式碼規範、PR 流程 |
1.2 README 的黃金結構
一個好的 README 應該包含：
- 專案名稱 + 一句話描述：讓人 3 秒內知道這是什麼
- 快速開始：最少步驟跑起來
- 功能特性：核心賣點
- 安裝方式：詳細的環境需求和安裝步驟
- 使用範例：可複製貼上的程式碼
- 貢獻指南：如何參與
- 授權條款：法律資訊
2. 寫作原則
2.1 清晰優先
markdown
<!-- 差：模糊不清 -->
這個函式處理資料。
<!-- 好：具體明確 -->
將原始訂單資料轉換為發票格式，包含稅費計算和幣別轉換。2.2 面向讀者
寫文件前先問：誰會讀這個文件？他們需要什麼資訊？
- 給新手寫：解釋術語，提供完整範例
- 給有經驗的開發者寫：直奔主題，提供 API 參考
- 給非技術人員寫：用類比，避免術語
2.3 程式碼範例是最好的文件
markdown
<!-- 差：只有文字描述 -->
呼叫 createUser 函式，傳入使用者名稱和電子郵件參數。
<!-- 好：給出可執行的範例 -->
const user = await createUser({
name: '張三',
email: 'zhangsan@example.com'
})
// 回傳: { id: 'u_123', name: '張三', createdAt: '2025-01-15' }3. 實戰對比
透過下面的互動元件，對比好的技術寫作和差的技術寫作：
Technical writing comparison - click to switch cases
❌ Poor writing
// Process data
function process(d) {
// ...
}✅ Better writing
/**
* Convert raw order data into invoice format.
* @param {Order} order - Raw order object
* @returns {Invoice} Formatted invoice
* @throws {ValidationError} When order data is incomplete
*/
function toInvoice(order) {
// ...
}Improvement points:Explain why, not just whatDocument parameter and return typesDescribe exceptional cases
3.1 Commit Message 規範
# 差
fix bug
update code
# 好（Conventional Commits）
fix: 修復登入頁在 Safari 下白屏的問題
feat: 支援批次匯出 PDF 格式報表
docs: 更新 API 認證章節的範例程式碼3.2 註解的藝術
javascript
// 差：描述「是什麼」（程式碼已經說了）
// 遍歷陣列
for (const item of items) { ... }
// 好：解釋「為什麼」
// 倒序遍歷，因為刪除元素時正序會跳過下一個
for (let i = items.length - 1; i >= 0; i--) { ... }4. 文件維護
4.1 文件即程式碼
把文件和程式碼放在同一個儲存庫，用同樣的工作流管理：
- 文件變更隨程式碼一起提交 PR
- CI 檢查文件格式和連結有效性
- 版本發布時同步更新文件
4.2 避免文件腐爛
| 問題 | 解決方案 |
|---|---|
| 文件過時 | 程式碼變更時強制更新文件（PR 檢查） |
| 無人維護 | 指定文件負責人 |
| 內容重複 | 單一資訊來源，其他地方引用連結 |
5. AI 助力：用大模型提升文件品質
大模型在技術寫作領域幾乎是「天賦異稟」——產生文件、改善表達、翻譯內容都是它的強項。
5.1 產生 API 文件
提示詞：
根據以下 Express 路由程式碼，產生完整的 API 文件，包括： - 端點路徑和方法 - 請求參數（路徑參數、查詢參數、請求體）及類型 - 成功和錯誤的回應範例 - 使用 curl 的呼叫範例 [貼上你的路由程式碼]
5.2 改善技術寫作
提示詞：
請改善以下技術文件的表達，要求： 1. 語言簡潔清晰，去掉冗餘表述 2. 用主動語態替代被動語態 3. 專業術語保持準確 4. 添加必要的程式碼範例 保持原意不變，只改善表達品質。 [貼上你的文件內容]
5.3 產生 README
提示詞：
根據以下專案資訊，產生一份高品質的 README.md： - 專案名稱：[名稱] - 一句話描述：[描述] - 技術棧：[列出] - 核心功能：[列出] 要求包含：專案簡介、快速開始、功能特性、 安裝步驟（含程式碼）、使用範例、貢獻指南、授權條款。
AI 使用建議
AI 產生的文件要檢查技術細節是否準確——它可能編造不存在的 API 參數或錯誤的回傳值。始終對照實際程式碼驗證。
6. 總結
- 類型匹配：不同文件有不同的結構和寫法
- 清晰優先：具體、準確、面向讀者
- 範例驅動：好的程式碼範例勝過千言萬語
- 持續維護：文件即程式碼，隨專案一起演進
終極思考
寫文件不是浪費時間，而是節省未來的時間。你今天花 30 分鐘寫的文件，可能幫 10 個人各節省 1 小時。好的文件是對團隊最好的投資。
延伸閱讀
- 寫作指南：Google 的技術寫作課程（Technical Writing）免費且實用。
- 文件工具：VitePress、Docusaurus、GitBook 等現代文件框架。
- API 文件：OpenAPI/Swagger 規範是 API 文件的業界標準。
- 實踐建議：從為自己的專案寫一個好的 README 開始。