用 AI 寫技術文件的工作流與品質管控

一句話說明

AI 可以從程式碼自動產出 API 參考文件和 README 骨架，但架構決策的脈絡、新人上手指南和疑難排解文件，仍然需要人類撰寫。

AI 寫技術文件的擅長領域

API 參考文件。給 AI 一個函式或類別的原始碼，它可以產出參數說明、回傳值描述、使用範例。這類文件的結構固定、內容可以從程式碼推論，AI 的產出品質通常可以直接使用，只需要微調用語。

Prompt 範例：

以下是一個 Python 函式，請產出它的 API 文件，包含：
- 功能說明（一句話）
- 參數表格（名稱、型別、必填/選填、說明）
- 回傳值說明
- 使用範例（含 import）
- 可能拋出的例外

def create_user(name: str, email: str, role: str = "viewer", 
                notify: bool = True) -> dict:

README 骨架。新專案的 README 通常需要：專案簡介、安裝步驟、快速開始、設定說明、API 概覽、貢獻指南。AI 可以根據 package.json 或 pyproject.toml 的內容，加上專案目錄結構，產出一份結構完整的 README 初稿。

Changelog 摘要。給 AI 一段時間的 git log，它可以整理出使用者看得懂的更新說明。例如把 "fix: handle null pointer in user.service.ts" 轉成「修復特定情況下用戶頁面當機的問題」。

程式碼註解補充。對於缺少註解的既有程式碼，AI 可以逐函式補上 docstring。這對接手別人程式碼的情況很有幫助，但 AI 加的註解有時只是把函式名稱換個說法（例如 get_user 的註解是「取得使用者」），缺乏有用的上下文資訊。

AI 寫不好的技術文件

架構決策紀錄（ADR）。為什麼選 PostgreSQL 而不是 MongoDB？為什麼用 event-driven 而不是 REST？這些決策背後的考量——團隊的技術能力、系統的擴展需求、時程壓力、相容性限制——AI 無從得知，它只能看到最終的程式碼，看不到做決策時的脈絡。

新人上手指南（Onboarding Guide）。哪些環境變數要設定、本機開發需要先跑什麼服務、測試資料怎麼建、哪些模組的程式碼風格跟其他地方不一樣——這些通常不在程式碼裡，而是在團隊成員的腦袋裡。AI 產出的上手指南往往只有通用步驟（安裝 Node.js、執行 npm install），缺少專案特有的坑。

疑難排解指南（Troubleshooting Guide）。「部署後 API 回傳 502」的排查步驟，牽涉到基礎架構配置、日誌位置、常見的環境差異。這類知識來自實際的維運經驗，AI 只能產出通用的排查建議（檢查 log、重啟服務），缺少針對你的系統的具體指引。

跨系統整合文件。描述 A 系統和 B 系統之間的資料流、認證方式、錯誤處理機制。這需要對兩個系統都有深入了解，AI 通常只能處理單一系統的文件。

實際工作流程

一個把 AI 嵌入文件產出流程的實際做法：

第一步：程式碼作為輸入。開發者寫完程式碼後，把相關的原始碼、型別定義、介面定義餵給 AI，讓它產出文件初稿。

第二步：AI 產出初稿。針對不同的文件類型使用不同的 Prompt。API 參考文件的 Prompt 著重在參數和回傳值；教學文件的 Prompt 著重在使用情境和步驟。

第三步：人工審查與補充。開發者審查 AI 的初稿，補充 AI 寫不出的部分：為什麼用這個設計、有哪些已知限制、哪些邊界條件需要注意。這一步通常花原本手動撰寫時間的 30-40%。

第四步：發布與版本控制。文件跟程式碼一起提交到 Git，透過 CI/CD 自動部署到文件網站。

Docs-as-Code：整合進 CI/CD

把 AI 文件產出整合進持續整合流程的具體做法：

Pre-commit hook。在 commit 時自動檢查新增或修改的函式是否有對應的文件。如果沒有，用 AI 產出初稿並提醒開發者審查。

# .github/workflows/docs-check.yml
name: Docs Check
on: [pull_request]
jobs:
  check-docs:
    runs-on: ubuntu-latest
    steps:
      - name: Check for undocumented functions
        run: |
          # 找出新增的 public 函式
          git diff origin/main --name-only -- '*.ts' '*.py' | \
            xargs grep -l 'export function\|def ' | \
            while read f; do
              echo "Checking docs for: $f"
            done

文件站部署。用 MkDocs 或 Docusaurus 搭建文件網站，PR 合併時自動重新部署。AI 產出的文件和人工撰寫的文件放在同一個目錄結構下，統一管理。

版本同步。在 CI 中加入檢查：如果某個函式的簽名（signature）改了，但對應的文件沒有更新，發出警告。這可以搭配 AI 自動產出更新建議。

衡量文件品質

AI 產出的文件到底有沒有用？以下是幾個可以量化的指標：

支援工單減少率。追蹤文件更新前後，相關主題的支援工單數量變化。如果 AI 產出的 API 文件讓「如何呼叫 XX API」的工單減少了 40%，代表文件有效。

Time-to-First-API-Call。新的 API 使用者從看到文件到成功發出第一個 API 呼叫的時間。好的文件（包含可直接複製的範例）可以把這個時間從 30 分鐘壓到 5 分鐘。

文件搜尋後的跳出率。如果使用者搜尋某個主題、點進文件頁面後馬上離開，代表文件內容沒有回答他們的問題。AI 產出的文件特別容易有這個問題——結構看起來完整，但缺少解決實際問題的內容。

開發者滿意度調查。每季做一次簡短的調查：「你上次查文件時，有找到你需要的資訊嗎？」這是最直接的品質指標。

安全考量

不要把內部 API 金鑰放進 Prompt。在請 AI 產出 API 文件時，範例中可能包含真實的 API endpoint 和金鑰。使用 placeholder（如 YOUR_API_KEY）取代真實值。

Staging 環境的 URL 不要外流。AI 產出的文件範例中可能包含你在 Prompt 裡提供的 staging URL。這些 URL 通常沒有正式環境的安全防護，外流後可能被用來做未授權存取。

基礎架構細節要脫敏。在讓 AI 產出部署文件時，不要提供真實的伺服器 IP、資料庫連線字串、VPN 設定。用變數（如 ${DB_HOST}）取代。

開源專案的特別注意。如果你的專案是開源的，AI 產出的文件會公開在 GitHub 上。確認文件中沒有洩漏內部工具名稱、內部通訊頻道、或只有團隊成員才知道的資訊。

限制

AI 產出的文件傾向「正確但沒用」。語法正確、結構完整，但缺少讓讀者真正理解的上下文。例如 AI 會寫「timeout 參數設定請求超時時間」，但不會告訴你「預設 30 秒對大多數場景夠用，但如果呼叫的是批次處理 API，建議設到 120 秒」。

AI 不知道文件的讀者是誰。寫給前端工程師的文件和寫給 DevOps 的文件，需要的細節程度和術語不同。AI 傾向寫出一個中間值，對兩邊都不夠好。除非你在 Prompt 中明確指定讀者。

過時的程式碼範例。AI 訓練資料有截止日期。它可能產出使用舊版 API 或已棄用函式的範例。所有程式碼範例都要在當前環境中實際測試。

知識檢測

讀完文章後，測試一下你對這個主題的理解。

常見問題

相關文章

• 用 AI 做 Code Review
• AI 生成程式碼的安全稽核
• 什麼是 Vibe Coding？

參考資料

• Write the Docs — Documentation principles
• Google Developer Documentation Style Guide
• Docs as Code — Anne Gentle