如何於每次發布時自動更新說明文件

更新於 2026 年 11 月 3 日

若要於每次發布時自動更新說明文件，請從發布本身啟動說明文件作業：例如已發布的 GitHub Release、GitLab 發布事件、Bitbucket 標籤，或是公開更新日誌中的新項目。此作業會讀取發布說明，找出受影響的說明頁面與影片，草擬變更內容並發送給專人審核。對於面向客戶的說明文件，此審核步驟是確保文件自動化安全無虞的關鍵。

本指南將先介紹如何使用任何工具（GitHub Actions、GitLab、Bitbucket、更新日誌頁面）執行此流程，接著展示 Clevera 的 Autopilot 如何為包含影片的說明中心執行相同的循環作業。

什麼是持續性說明文件 (Continuous Documentation)？#

推廣此概念的 Swimm 將 持續性說明文件 定義為在開發工作流程中逐步建立與更新文件，而非透過偶爾進行的補救專案。大多數基於此理念建構的工具（現常被稱為「自我更新說明文件」）會監控提交 (commits) 或合併請求 (pull requests)，並在程式碼旁更新開發者文件。

面向客戶的說明中心需要不同的觸發機制。讀者看不到程式碼提交，他們看到的是「發布」。下表顯示了其中的權衡。

自動化的理由在於速度。DORA 2021 年的 DevOps 現狀研究發現，菁英團隊的部署頻率比低效能團隊高出 973 倍。並非每次部署都會改變讀者所見的內容，但團隊發布的頻率遠高於人工重新檢查文章的速度。同一項研究發現，擁有高品質說明文件的團隊，實施安全最佳實踐的可能性高出 3.8 倍，因此說明文件絕非次要議題。過時的文件相當常見：在 GitHub 2017 年的開源調查中，93% 的受訪者曾遇到不完整或過時的說明文件，且 60% 的貢獻者表示他們很少或從不為說明文件做出貢獻。

第 1 步：撰寫說明文件作業可用的發布說明#

自動化更新文件的品質，取決於發布說明對變更的描述程度。以下兩個慣例很有幫助。

• 按類型分組變更。 Keep a Changelog 使用 Added (新增)、Changed (變更)、Deprecated (棄用)、Removed (移除)、Fixed (修正) 與 Security (安全性)。「新增」通常代表新的文章或影片；「變更」與「移除」則代表現有內容已不正確。
• 區分使用者可見與不可見的變更。 GitHub 的 自動產生發布說明 會根據 .github/release.yml 中的標籤對合併請求進行分類，並可完全排除特定標籤。

# .github/release.yml
changelog:
  exclude:
    labels: [internal, chore]
  categories:
    - title: New
      labels: [feature]
    - title: Changed in the app
      labels: [ui-change]
    - title: Fixes
      labels: [bug]
    - title: Other changes
      labels: ["*"]

「ui-change」標籤是最實用的標籤：它能告訴說明文件作業哪些項目可能會導致文章失效。同時在合併請求標題中註明畫面名稱（例如「帳單設定：將提醒移至自動化」），以便將變更對應到顯示該畫面的頁面。

第 2 步：於發布時自動更新說明文件：啟動作業#

每個主要的 Git 託管平台都能在您發布時啟動作業，這就是如何從 GitHub Release 或其 GitLab 與 Bitbucket 對應功能產生文件更新的方法。細節各不相同。

在 GitHub 上，一個最小化的工作流程如下所示：

# .github/workflows/docs-on-release.yml
name: Docs on release
on:
  release:
    types: [published]
permissions:
  contents: read
jobs:
  draft-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false
      - name: Draft docs updates for this release
        env:
          TAG: ${{ github.event.release.tag_name }}
          NOTES: ${{ github.event.release.body }}
        run: ./scripts/draft-docs-updates.sh

請使用 published 而非 created：根據 GitHub 的 事件參考，created 不會針對草稿發布觸發，而 published 則涵蓋穩定版與預發布版。請如上所示透過環境變數傳遞發布說明，不要直接傳入 shell 指令，因為發布文字屬於使用者輸入。此外，若 release-please 或 semantic-release 等工具使用預設權杖建立發布，其觸發的事件將不會啟動您的說明文件工作流程；請改為提供該工具 GitHub App 權杖或個人存取權杖。

在 GitLab 與 Bitbucket 上，對應的做法是執行於標籤上的作業：

# .gitlab-ci.yml
draft-docs:
  rules:
    - if: $CI_COMMIT_TAG
  script:
    - ./scripts/draft-docs-updates.sh "$CI_COMMIT_TAG"

# bitbucket-pipelines.yml
pipelines:
  tags:
    'v*':
      - step:
          script:
            - ./scripts/draft-docs-updates.sh "$BITBUCKET_TAG"

第 3 步：找出每次發布影響的頁面與影片#

這是大多數指南會跳過的步驟，也是決定自動化是否有幫助的關鍵。發布說明寫著「提醒移至帳單 → 自動化」；您的作業必須將其轉化為「這三篇文章與兩部影片現在已不正確」。

三種方法，由簡入深：

1. 搜尋重新命名的標籤。 從發布說明中提取所有引用的 UI 字串，並在您的文章與影片腳本中搜尋舊的措辭。
2. 建立畫面清單。 為每篇文章與影片標記其顯示的畫面，並將合併請求標題中的畫面名稱與其比對。我們的 保持說明文件最新 指南中提供了一份清單範本。
3. 讓模型完整讀取每個候選項目。 將發布說明與每篇候選頁面的全文（或逐字稿）提供給語言模型，並要求判斷：內容是否仍正確、是否需要文字修正，或是需要新的截圖或影像。讀取整頁內容至關重要，因為失效的步驟通常不是發布說明中提到的那個。

用於此判斷的提示詞可以很簡短：

You check help articles against a software release.
Release notes: {release_notes}
Article ({url}): {article_text}

Answer in JSON: {"verdict": "still_right" | "text_fix" | "new_screenshots_or_footage",
"reason": "<one sentence quoting the release item>",
"changed_steps": [<step numbers>]}
Only use facts from the release notes. If unsure, answer "text_fix" and say why.

第 4 步：草擬更新內容#

對於文字，草擬是最簡單的部分：模型會接收發布說明、當前文章與您的風格規範，並回傳修訂版本。請保留文章的 ID 與 URL，以便更新現有頁面而非建立近乎重複的內容，並記錄最後一次變更它的發布版本。如何撰寫說明中心文章 中的規則是很好的風格提示詞。

截圖與影片則較困難。模型無法產生它未見過的畫面截圖。您必須在 UI 測試套件中擷取新影像、重新錄製變更後的流程，或標記項目由專人重新錄製。在計畫中標記每個項目：文字修正、新截圖或重新錄製。一旦變更後的流程錄製完成，將錄製內容轉化為說明文件 即可一次完成新步驟與截圖的製作。

第 5 步：在草稿與讀者之間安排人工審核#

合併請求說明由許多人撰寫，且從未考慮到客戶需求。請將它們與發布說明視為不可信的輸入：它們可能包含模型會遵循的指令。請將每份草稿送交審核。

• 審核者： 說明中心內容由支援或文件負責人審核，API 參考則由工程師審核。
• 優質審核的內容： 顯示每個受影響頁面的修改前後對照 (diff)、導致變更的發布項目，以及一份明確的「無需變更」清單，讓審核者信任被跳過的項目。
• 自動發布的內容： 起初不要自動發布任何面向客戶的內容。在幾次發布且未出現意外後，您可以放寬規則，針對低風險項目（如錯字級別的文字修正）進行自動化。

哪種設定適合您的團隊？#

如果您的團隊已經在使用 Claude Code，您也可以透過 MCP 要求它在發布後更新文件；我們在 如何於每次發布後使用 Claude Code 更新文件 中有詳細說明。

如何使用 Clevera Autopilot 在發布時自動更新文件#

Clevera 是一個 AI 平台，能將螢幕錄影轉化為帶有旁白的教學影片、逐步說明文章以及託管式說明中心頁面，並支援 74 種語言。其 Autopilot 功能（適用於 Pro 與 Custom 方案）可為 Clevera 說明中心執行上述第 2 至第 5 個步驟。

• 觸發條件。 「在我們發布時保持說明中心更新」配方會監控儲存庫的「發布 (Releases)」或「已合併變更 (Merged changes)」，或是每日或每週讀取的「更新日誌頁面」。GitHub 透過唯讀應用程式連結；GitLab (gitlab.com) 與 Bitbucket Cloud 在可用時採用相同方式連結。Clevera 約每小時檢查一次儲存庫。它會讀取發布說明、標籤以及 PR 標題與說明，絕不會讀取您的程式碼。
• 比對。 每次執行會檢查說明中心內最多 40 部影片與文章，並完整讀取受影響的內容。
• 草擬。 每個項目都會獲得一個判定結果：內容正確、顯示修改前後對比的文字修正，或是使用新步驟「重新錄製」。重新錄製需要「使用我的應用程式」：提供應用程式網址，若有需要則提供登入資訊（測試帳號效果最佳）。新影片會取代相同連結的舊影片，因此如同 LiveSync 編輯一樣，嵌入內容與說明中心頁面無需更新連結即可顯示。
• 審核。 每次執行都會等待您的確認。您可以取消勾選不想更新的項目並點擊「執行」，或點擊「要求變更」以取得新方案。方案會在七天後過期，下一次執行會涵蓋期間內的所有變更。

監控與規劃功能為免費；方案中的每一行都會顯示所需點數，一般執行約需 10 到 150 點。若沒有說明中心，同樣的循環也適用於影片，透過「當產品變更時更新我的影片」功能，而「為每個新功能錄製影片」則會針對每次發布新增的內容建議新的教學（請參閱 如何製作發布說明影片 的手動版本）。

Clevera 不適用的場景：它不會從程式碼產生 API 參考文件，也不會撰寫您的 CHANGELOG.md。關於這部分，請參閱我們的 AI 更新日誌產生器 比較，或若您希望 AI 代理在其他平台編輯文件，請參閱 文件專用的 MCP 伺服器。

免費開始 以先建立說明中心與影片；Autopilot 包含在 Pro 方案中。設定步驟請參閱說明文章 將 GitHub 或其他儲存庫連線至 Autopilot。

常見問題#

文件可以在我們發布時自動更新嗎？#

偵測與草擬過程可以是自動的：發布會啟動一個作業，找出受影響的頁面並草擬修正內容。對於面向客戶的文件，發布應由人工決定，因為發布說明並不總是能準確表達您希望讀者執行的操作。

文件應該在每次提交 (commit) 還是每次發布時更新？#

對於說明中心，建議在每次發布時更新。提交與 PR 變更頻繁且常隱藏在功能旗標後；發布才是讀者真正看到變更的時刻。與程式碼並存的開發者文件則可以跟隨 PR 更新。

如何在發布時觸發 GitHub Action？#

使用 on: release 搭配 types: [published]。如果發布是由另一個使用預設 GITHUB_TOKEN 的工作流程所建立，它將不會啟動您的工作流程；請為發布工具使用 GitHub App Token 或個人存取權杖 (PAT)。

如果我們不在 GitHub 上發布怎麼辦？#

使用您現有的訊號：GitLab 發布事件、Bitbucket 標籤管線，或是讀取公開更新日誌頁面或其 RSS 饋送的排程作業。Clevera 的 Autopilot 正是為了這種情況，可以每日或每週監控更新日誌頁面。

截圖與影片也能自動更新嗎？#

截圖可以在每次建置時透過 UI 測試進行擷取。影片則需要重新錄製變更後的流程；AI 錄影機可以針對新 UI 重新執行已儲存的指令，當您提供應用程式網址（若有需要則提供登入資訊）時，Autopilot 即可為 Clevera 影片執行此操作。請在核准前先預覽新錄製的內容。