Cách tự động cập nhật tài liệu sau mỗi bản phát hành

Cập nhật ngày 3 tháng 11 năm 2026

Để tự động cập nhật tài liệu sau mỗi bản phát hành, hãy bắt đầu một tác vụ tài liệu từ chính bản phát hành đó: một bản phát hành GitHub đã xuất bản, một sự kiện phát hành GitLab, một thẻ Bitbucket hoặc một mục mới trên nhật ký thay đổi công khai của bạn. Tác vụ này đọc ghi chú phát hành, tìm các trang trợ giúp và video mà bản phát hành ảnh hưởng, soạn thảo các thay đổi và gửi chúng cho một người để phê duyệt. Đối với tài liệu hướng tới khách hàng, bước xem xét đó là điều giúp việc tự động hóa tài liệu trở nên an toàn.

Hướng dẫn này đi qua quy trình đó với bất kỳ công cụ nào trước tiên (GitHub Actions, GitLab, Bitbucket, trang nhật ký thay đổi), sau đó cho thấy cách Autopilot của Clevera chạy cùng một vòng lặp cho trung tâm trợ giúp với video.

Tài liệu liên tục là gì?#

Swimm, đơn vị phổ biến thuật ngữ này, định nghĩa tài liệu liên tục là việc tạo và cập nhật tài liệu tăng dần như một phần của quy trình phát triển, thay vì trong các dự án bù đắp không thường xuyên. Hầu hết các công cụ được xây dựng dựa trên ý tưởng này, hiện thường được bán dưới dạng "tài liệu tự cập nhật", theo dõi các commit hoặc pull request và cập nhật tài liệu nhà phát triển bên cạnh mã nguồn.

Các trung tâm trợ giúp hướng tới khách hàng cần một trình kích hoạt khác. Người đọc không thấy commit; họ thấy một bản phát hành. Bảng dưới đây cho thấy sự đánh đổi.

Lý do cho việc tự động hóa là tốc độ. Nghiên cứu State of DevOps năm 2021 của DORA cho thấy các nhóm ưu tú triển khai thường xuyên hơn 973 lần so với các nhóm hiệu suất thấp. Không phải mọi lần triển khai đều thay đổi những gì người đọc thấy, nhưng các nhóm xuất xưởng thường xuyên hơn nhiều so với bất kỳ ai có thể kiểm tra lại các bài viết bằng tay. Nghiên cứu tương tự cho thấy các nhóm có tài liệu chất lượng cao có khả năng thực hiện các phương pháp bảo mật tốt nhất cao gấp 3,8 lần, vì vậy tài liệu không phải là vấn đề phụ. Và tài liệu lỗi thời rất phổ biến: trong Khảo sát Nguồn mở năm 2017 của GitHub, 93% người trả lời đã gặp phải tài liệu không đầy đủ hoặc lỗi thời, và 60% người đóng góp cho biết họ hiếm khi hoặc không bao giờ đóng góp vào tài liệu.

Bước 1: Viết ghi chú phát hành mà tác vụ tài liệu có thể sử dụng#

Tự động hóa chỉ có thể cập nhật tài liệu tốt như cách ghi chú phát hành mô tả thay đổi. Hai quy ước sẽ giúp ích.

• Nhóm các thay đổi theo loại. Keep a Changelog sử dụng Added (Đã thêm), Changed (Đã thay đổi), Deprecated (Đã ngừng hỗ trợ), Removed (Đã xóa), Fixed (Đã sửa) và Security (Bảo mật). "Added" thường có nghĩa là một bài viết hoặc video mới; "Changed" và "Removed" có nghĩa là nội dung hiện có bây giờ đã sai.
• Tách biệt những gì người dùng thấy với những gì họ không thấy. Ghi chú phát hành được tạo tự động của GitHub sắp xếp các pull request đã hợp nhất theo nhãn trong .github/release.yml, và có thể loại trừ hoàn toàn các nhãn.

# .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: ["*"]

Nhãn "ui-change" là nhãn hữu ích nhất để thêm vào: nó cho tác vụ tài liệu biết những mục nào có thể làm hỏng một bài viết. Hãy đặt tên màn hình trong tiêu đề pull-request nữa ("Cài đặt thanh toán: di chuyển lời nhắc sang Tự động hóa"), để thay đổi có thể được khớp với các trang hiển thị màn hình đó.

Bước 2: Tự động cập nhật tài liệu khi phát hành: bắt đầu một tác vụ#

Mọi máy chủ Git lớn đều có thể bắt đầu một tác vụ khi bạn xuất xưởng, đó là cách bạn tạo các bản cập nhật tài liệu từ các bản phát hành GitHub hoặc các bản tương đương trên GitLab và Bitbucket. Các chi tiết khác nhau.

Trên GitHub, một quy trình làm việc tối thiểu trông như thế này:

# .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

Sử dụng published thay vì created: theo tham chiếu sự kiện của GitHub, created không kích hoạt cho các bản phát hành nháp, trong khi published bao gồm cả bản phát hành ổn định và bản phát hành trước. Chuyển ghi chú phát hành qua một biến môi trường như trên, không phải trực tiếp vào lệnh shell, vì văn bản phát hành là đầu vào của người dùng. Và nếu một công cụ như release-please hoặc semantic-release tạo các bản phát hành của bạn với token mặc định, các sự kiện nó kích hoạt sẽ không bắt đầu quy trình làm việc tài liệu của bạn; hãy cấp cho công cụ đó một token GitHub App hoặc một token truy cập cá nhân thay thế.

Trên GitLab và Bitbucket, tương đương là một tác vụ chạy trên các thẻ:

# .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"

Bước 3: Tìm các trang và video mà mỗi bản phát hành ảnh hưởng#

Đây là bước mà hầu hết các hướng dẫn bỏ qua, và là bước quyết định liệu tự động hóa có giúp ích hay không. Một ghi chú phát hành nói "Lời nhắc đã di chuyển sang Thanh toán → Tự động hóa"; tác vụ của bạn phải biến điều đó thành "ba bài viết và hai video này hiện đã sai".

Ba phương pháp, từ đơn giản nhất đến mạnh mẽ nhất:

1. Tìm kiếm các nhãn đã đổi tên. Lấy mọi chuỗi giao diện người dùng trong dấu ngoặc kép ra khỏi ghi chú phát hành và tìm kiếm các bài viết và kịch bản video của bạn cho cách diễn đạt cũ.
2. Giữ một danh mục màn hình. Gắn thẻ mỗi bài viết và video với các màn hình mà nó hiển thị, và khớp tên màn hình trong tiêu đề pull-request với nó. Hướng dẫn của chúng tôi về giữ tài liệu cập nhật có một mẫu danh mục.
3. Để một mô hình đọc từng ứng viên đầy đủ. Cung cấp cho một mô hình ngôn ngữ các ghi chú phát hành và toàn bộ văn bản (hoặc bản ghi) của từng trang ứng viên, và yêu cầu một phán quyết: vẫn đúng, cần sửa văn bản, hoặc cần ảnh chụp màn hình hoặc cảnh quay mới. Đọc toàn bộ trang là quan trọng, vì bước bị hỏng thường không phải là bước mà ghi chú phát hành nêu tên.

Một lời nhắc cho phán quyết đó có thể ngắn gọn:

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.

Bước 4: Soạn thảo các bản cập nhật#

Đối với văn bản, bản nháp là phần dễ dàng: mô hình nhận ghi chú phát hành, bài viết hiện tại và các quy tắc phong cách của bạn, và trả về một phiên bản đã sửa đổi. Giữ ID và URL của bài viết, để bạn cập nhật trang hiện có thay vì tạo một bản sao gần giống, và ghi lại bản phát hành nào đã thay đổi nó lần cuối. Các quy tắc trong cách viết bài viết trung tâm trợ giúp tạo ra một lời nhắc phong cách tốt.

Ảnh chụp màn hình và video khó hơn. Một mô hình không thể tạo ra ảnh chụp màn hình của một màn hình mà nó chưa thấy. Bạn hoặc chụp ảnh mới trong bộ kiểm thử giao diện người dùng của mình, ghi lại luồng đã thay đổi, hoặc gắn cờ mục đó để một người ghi lại. Đánh dấu từng mục trong kế hoạch: sửa văn bản, ảnh chụp màn hình mới, hoặc ghi lại. Sau khi luồng đã thay đổi được ghi lại, biến bản ghi thành tài liệu cung cấp cho bạn các bước và ảnh chụp màn hình mới trong một lần thực hiện.

Bước 5: Đặt một người giữa bản nháp và người đọc#

Mô tả pull-request được viết bởi nhiều người và không bao giờ được xem xét với khách hàng trong tâm trí. Hãy coi chúng, và ghi chú phát hành, là đầu vào không đáng tin cậy: chúng có thể mang các hướng dẫn mà một mô hình sẽ làm theo. Gửi mọi bản nháp để xem xét.

• Ai phê duyệt: trưởng bộ phận hỗ trợ hoặc tài liệu cho nội dung trung tâm trợ giúp, một kỹ sư cho tham chiếu API.
• Một bài đánh giá tốt cho thấy gì: mỗi trang bị ảnh hưởng với sự khác biệt trước và sau, mục phát hành gây ra nó, và một danh sách "không có gì để thay đổi" rõ ràng để người đánh giá tin tưởng những gì đã bị bỏ qua.
• Những gì cần xuất bản tự động: ban đầu không có gì hướng tới khách hàng. Khi một vài bản phát hành đã thông qua mà không có bất ngờ, bạn có thể nới lỏng quy tắc cho các mục rủi ro thấp như sửa lỗi văn bản cấp độ lỗi chính tả.

Thiết lập nào phù hợp với nhóm của bạn?#

Nếu nhóm của bạn đã làm việc trong Claude Code, bạn cũng có thể yêu cầu nó cập nhật tài liệu sau khi phát hành qua MCP; chúng tôi hướng dẫn chi tiết trong bài cách cập nhật tài liệu với Claude Code sau mỗi bản phát hành.

Cách tự động cập nhật tài liệu khi phát hành với Clevera Autopilot#

Clevera là nền tảng AI biến bản ghi màn hình thành video hướng dẫn có lời bình, bài viết hướng dẫn từng bước và một trang trên trung tâm hỗ trợ của bạn, hỗ trợ 74 ngôn ngữ. Tính năng Autopilot của chúng tôi, có trong gói Pro và Custom, thực hiện các bước từ 2 đến 5 ở trên cho trung tâm hỗ trợ Clevera.

• Kích hoạt. Công thức Giữ trung tâm hỗ trợ luôn cập nhật khi chúng tôi phát hành sẽ theo dõi các Bản phát hành hoặc Thay đổi đã hợp nhất của kho lưu trữ, hoặc Trang nhật ký thay đổi được đọc hàng ngày hoặc hàng tuần. GitHub kết nối thông qua ứng dụng chỉ đọc; GitLab (gitlab.com) và Bitbucket Cloud kết nối theo cách tương tự nếu có. Clevera kiểm tra kho lưu trữ khoảng một giờ một lần. Nó đọc ghi chú phát hành, thẻ và tiêu đề/mô tả pull-request, không bao giờ đọc mã nguồn của bạn.
• Đối chiếu. Mỗi lần chạy sẽ kiểm tra tối đa 40 video và bài viết của trung tâm hỗ trợ và đọc toàn bộ nội dung từng mục bị ảnh hưởng.
• Soạn thảo. Mỗi mục sẽ nhận được một kết luận: vẫn chính xác, một bản sửa văn bản hiển thị trước và sau, hoặc quay lại với các bước mới. Việc quay lại cần Sử dụng ứng dụng của tôi: địa chỉ ứng dụng của bạn và thông tin đăng nhập nếu cần (tài khoản thử nghiệm là tốt nhất). Video mới thay thế video cũ tại cùng một liên kết, vì vậy, giống như các chỉnh sửa LiveSync, các nội dung nhúng và trang trung tâm hỗ trợ sẽ hiển thị video mới mà không cần liên kết mới.
• Duyệt. Mỗi lần chạy đều chờ bạn phê duyệt. Bạn bỏ chọn những mục không muốn và nhấp Chạy, hoặc nhấp Yêu cầu thay đổi để có kế hoạch mới. Kế hoạch sẽ hết hạn sau bảy ngày và lần chạy tiếp theo sẽ lấy tất cả các thay đổi kể từ đó.

Việc theo dõi và lập kế hoạch là miễn phí; mỗi dòng trong kế hoạch hiển thị số tín dụng cần thiết, và một lần chạy thông thường tốn từ 10 đến 150 tín dụng. Vòng lặp tương tự cũng khả dụng cho video mà không cần trung tâm hỗ trợ thông qua Cập nhật video của tôi khi sản phẩm thay đổi, và Quay video cho mỗi tính năng mới đề xuất một hướng dẫn mới cho những gì mỗi bản phát hành thêm vào (xem cách tạo video ghi chú phát hành cho phiên bản thủ công).

Nơi Clevera không phải là công cụ phù hợp: nó không tạo tài liệu tham khảo API từ mã nguồn hoặc viết CHANGELOG.md của bạn. Đối với phần đó, hãy xem bảng so sánh trình tạo nhật ký thay đổi bằng AI của chúng tôi, hoặc các máy chủ MCP cho tài liệu nếu bạn muốn một AI agent chỉnh sửa tài liệu trên nền tảng khác.

Bắt đầu miễn phí để xây dựng trung tâm hỗ trợ và video trước; Autopilot đi kèm với gói Pro. Các bước thiết lập có trong bài viết trợ giúp Kết nối GitHub hoặc kho lưu trữ khác với Autopilot.

Câu hỏi thường gặp#

Tài liệu có thể tự động cập nhật khi chúng tôi phát hành không?#

Việc phát hiện và soạn thảo có thể tự động: một bản phát hành bắt đầu một công việc tìm kiếm các trang bị ảnh hưởng và soạn thảo các bản sửa lỗi. Việc xuất bản nên là quyết định của con người đối với tài liệu hướng tới khách hàng, vì ghi chú phát hành không phải lúc nào cũng nói rõ ý định của bạn đối với người đọc.

Tài liệu nên cập nhật theo mỗi commit hay mỗi bản phát hành?#

Đối với trung tâm hỗ trợ, hãy cập nhật theo mỗi bản phát hành. Các commit và pull request thay đổi liên tục và thường nằm sau các cờ tính năng; bản phát hành là lúc người đọc thực sự thấy thay đổi. Tài liệu lập trình viên nằm cạnh mã nguồn có thể theo sát các pull request.

Làm thế nào để kích hoạt GitHub Action khi một bản phát hành được xuất bản?#

Sử dụng on: release với types: [published]. Nếu bản phát hành được tạo bởi một workflow khác sử dụng GITHUB_TOKEN mặc định, nó sẽ không khởi chạy workflow của bạn; hãy sử dụng token GitHub App hoặc token truy cập cá nhân cho công cụ phát hành.

Nếu chúng tôi không xuất bản các bản phát hành trên GitHub thì sao?#

Hãy sử dụng tín hiệu bạn có: sự kiện phát hành GitLab, pipeline thẻ Bitbucket, hoặc một công việc theo lịch trình đọc trang nhật ký thay đổi công khai hoặc nguồn RSS của nó. Autopilot của Clevera có thể theo dõi trang nhật ký thay đổi hàng ngày hoặc hàng tuần cho chính trường hợp này.

Ảnh chụp màn hình và video có thể được cập nhật tự động không?#

Ảnh chụp màn hình có thể được chụp trong các bài kiểm tra giao diện người dùng (UI tests) trên mỗi bản build. Video cần được quay lại quy trình đã thay đổi; một trình ghi AI có thể chạy lại hướng dẫn đã lưu trên giao diện người dùng mới, và Autopilot có thể thực hiện việc này cho video Clevera khi bạn cung cấp địa chỉ ứng dụng (và thông tin đăng nhập nếu cần). Hãy xem bản quay mới trước khi phê duyệt.