Trình tạo tài liệu AI: những gì nên tự động hóa và những gì không

Tháng trước, tôi đã chứng kiến một đội ngũ sản phẩm tung ra bản cập nhật giao diện người dùng tuyệt đẹp… và âm thầm đốt cháy trung tâm trợ giúp của họ.

Không phải theo nghĩa đen. Nhưng cũng gần như vậy.

Tài liệu vẫn hiển thị các nhãn nút cũ. Video giới thiệu vẫn hướng người dùng đến một menu không còn tồn tại. Bộ phận hỗ trợ bắt đầu nhận được những phiếu yêu cầu “Tôi bị kẹt” mang lại cảm giác như giẫm phải mảnh ghép LEGO trong bóng tối.

Đó là lúc sự cám dỗ ập đến: “Hãy sử dụng trình tạo tài liệu AI để tạo lại mọi thứ.”

Chắc chắn rồi. Và bạn cũng có thể cho bít tết vào lò vi sóng. Nó sẽ nhanh. Nhưng nó cũng sẽ rất tệ.

Đây là quy tắc chúng tôi sử dụng: tự động hóa các phần tài liệu hoạt động như sự thật, không phải các phần phụ thuộc vào sự phán đoán. Ngay khi quá trình tự động hóa của bạn bắt đầu đoán ý định, bạn đã đánh đổi “tài liệu cũ kỹ” lấy “hư cấu tự tin”.

(Và vâng, chúng tôi sẽ đề cập đến quay màn hình thành tài liệu và cách một trình tạo hướng dẫn từng bước thực sự nên hoạt động mà không khiến bạn phải xấu hổ sau này.)

Trình tạo tài liệu AI nên làm gì (và tại sao hầu hết đều thất bại)#

Trình tạo tài liệu AI là phần mềm biến các nguồn đáng tin cậy (như giao diện sản phẩm, lược đồ, nhật ký thay đổi và bản ghi) thành các bản nháp tài liệu cập nhật, sau đó giữ cho chúng luôn mới thông qua kiểm tra và đánh giá, để các đội ngũ phát hành nhanh hơn mà không xuất bản các hướng dẫn không chính xác.

Hầu hết các đội ngũ thất bại vì họ tự động hóa việc “viết” thay vì tự động hóa việc xác minh.

Tự động hóa có ROI cao nhất không phải là “tạo thêm nhiều trang”. Đó là “bắt kịp sự trôi dạt trước khi khách hàng làm điều đó.”

Sử dụng khung quyết định này: sự mơ hồ so với phạm vi ảnh hưởng#

Khi bạn quyết định những gì cần tự động hóa, hãy đặt hai câu hỏi:

1) Sự mơ hồ: tài liệu này có yêu cầu diễn giải và bối cảnh nội bộ không? 2) Phạm vi ảnh hưởng: ai sẽ bị ảnh hưởng nếu điều này sai?

• Độ mơ hồ thấp + phạm vi ảnh hưởng thấp = bạn có thể tự động hóa mạnh mẽ.
• Độ mơ hồ cao + phạm vi ảnh hưởng cao = chỉ tự động hóa dưới dạng hỗ trợ soạn thảo, với các cổng đánh giá nghiêm ngặt.

Nếu bạn muốn một câu hỏi thứ ba giúp cứu vãn sự nghiệp: Tôi có nguồn xác thực nào mà AI có thể trích dẫn không? (Nếu không, nó không nên tự động xuất bản.)

Tư duy này kết hợp tốt với quy trình làm việc “tài liệu như mã” nơi tài liệu được quản lý phiên bản, đánh giá và kiểm tra giống như phần mềm.

Những gì nên tự động hóa với trình tạo tài liệu AI (tín hiệu cao, độ mơ hồ thấp)#

Tạo tài liệu tham khảo từ các nguồn có cấu trúc#

Nếu “sự thật” của bạn nằm trong một lược đồ, hãy để lược đồ dẫn dắt.

• Lược đồ OpenAPI, AsyncAPI, GraphQL
• chữ ký kiểu, protobufs
• danh mục cấu hình

Điều này an toàn vì bạn có thể xác thực kết quả đầu ra dựa trên nguồn và tạo lại khi phát hành. Hướng dẫn OpenAPI hỗ trợ mạnh mẽ tư duy thiết kế ưu tiên cho các thông số kỹ thuật đáng tin cậy.

Soạn thảo tóm tắt thay đổi, không phải “sự thật cuối cùng”#

Tự động hóa:

• bản nháp ghi chú phát hành từ tiêu đề PR, nhãn và commit
• các khác biệt “những gì đã thay đổi” cho chủ sở hữu tài liệu

Sau đó, hãy giữ một bước chỉnh sửa của con người. AI nên làm nổi bật các thay đổi, không phải quyết định xem chúng có quan trọng hay không.

Duy trì danh mục tài liệu và chạy kiểm tra độ mới#

Tự động hóa:

• những trang nào tồn tại
• ai sở hữu chúng
• lần cuối chúng được xác minh so với phiên bản X
• những trang nào có khả năng bị trôi dạt sau khi phát hành

Đây là nơi danh mục dịch vụ tỏa sáng vì chúng kết nối quyền sở hữu với các hệ thống và giữ cho việc khám phá trở nên hợp lý.

Thực thi tính nhất quán và vệ sinh tài liệu#

Rủi ro thấp, lợi ích cao:

• tính nhất quán của thuật ngữ
• kiểm tra hướng dẫn phong cách
• liên kết hỏng
• định dạng đoạn mã

Các tài nguyên viết kỹ thuật của Google là một cơ sở vững chắc cho sự rõ ràng và nhất quán khi bạn cần sự “nhàm chán và dễ đọc”.

Cải thiện câu trả lời bằng truy xuất, không phải tạo tự do#

Đối với các câu hỏi nội bộ “làm thế nào để…?”, truy xuất tốt hơn là cảm tính.

Công việc của Anthropic về Truy xuất theo ngữ cảnh cho thấy những lợi ích lớn trong việc giảm lỗi truy xuất, điều này cải thiện trực tiếp độ tin cậy của RAG.

Những gì không nên tự động hóa (hoặc chỉ thực hiện sau khi SME đánh giá nghiêm ngặt)#

Nếu trình tạo tài liệu AI của bạn chạm vào bất kỳ điều nào sau đây, hãy thêm các cổng kiểm soát hoặc đừng tự động hóa nó chút nào:

Cơ sở lý luận và sự đánh đổi về kiến trúc#

AI có thể tóm tắt một ADR, nhưng nó không thể suy luận một cách đáng tin cậy “tại sao chúng ta chọn X” từ mã nguồn. Đó là cách bạn kết thúc với một tài liệu nghe có vẻ thông minh nhưng hoàn toàn sai.

Sách hướng dẫn vận hành có thể làm hỏng môi trường sản xuất#

Bất cứ điều gì thay đổi trạng thái sản xuất (khôi phục DB, các bước sự cố, xoay vòng khóa) đều cần một chủ sở hữu, diễn tập và đánh giá.

Hướng dẫn về bảo mật và quyền riêng tư#

Đừng để trình tạo tự động bình thường hóa các mẫu không an toàn hoặc làm rò rỉ cấu trúc liên kết nội bộ.

Các tuyên bố về hiệu suất và điểm chuẩn#

Nếu nó không được đo lường, đó là tiếp thị. Hãy để con người thực hiện việc này.

Các mẫu mã phải biên dịch hoặc chạy được#

Nếu bạn không thể kiểm tra nó trong CI, đừng tự động xuất bản nó.

Quy tắc chủ quan của tôi: Nếu bạn không thể xác thực nó, hãy dán nhãn “bản nháp” hoặc giữ nó ở chế độ riêng tư. Tôi đã thấy các tài liệu tự động “hữu ích” tạo ra nhiều công việc hơn là tiết kiệm được.

Quay màn hình thành tài liệu: lối tắt giúp bạn trung thực#

Đây là thủ thuật ít được sử dụng: khi sự mơ hồ cao, hãy ngừng yêu cầu AI “phát minh ra sự rõ ràng” và thay vào đó hãy cung cấp cho nó bằng chứng.

Một quy trình quay màn hình thành tài liệu tốt sẽ thay đổi mô hình:

• Nguồn sự thật không phải là văn xuôi của AI.
• Nguồn sự thật là quy trình làm việc được ghi lại: các cú nhấp chuột, trường, trạng thái giao diện người dùng và trình tự.

Đây chính xác là lý do tại sao chúng tôi xây dựng Clevera để biến các bản ghi màn hình thô, không tiếng thành video sản phẩm có lời dẫn và một bài viết có cấu trúc, giàu ảnh chụp màn hình trong một luồng duy nhất. Bản ghi cung cấp nền tảng, và tài liệu trở thành một bản phát lại trung thực, không phải là một bài tập viết sáng tạo.

CTA theo ngữ cảnh: Nếu đội ngũ của bạn cứ viết lại cùng một hướng dẫn “làm thế nào để” mỗi lần phát hành, hãy thử biến quy trình làm việc tiếp theo thành một bản ghi Clevera và xuất trực tiếp nó sang trung tâm trợ giúp của bạn hoặc, trên gói Pro trở lên, wiki của bạn. Bạn sẽ cảm nhận được sự khác biệt ngay lần đầu tiên không phải đuổi theo ảnh chụp màn hình.

Thông tin chi tiết không thể tìm thấy trên Google mà chúng tôi sử dụng nội bộ: Hãy coi mọi tài liệu hướng dẫn là “một bản phát lại”, không phải “một trang”. Nếu bạn không thể phát lại cách kết quả được tạo ra, bạn chỉ cách sự vô nghĩa một thay đổi giao diện người dùng.

Quy trình tạo hướng dẫn từng bước sẽ không khiến bạn xấu hổ#

Một trình tạo hướng dẫn từng bước chỉ trở nên đáng tin cậy khi bạn vận hành nó như một quy trình kỹ thuật, không phải một máy đánh bạc nội dung.

Đây là quy trình làm việc tôi đề xuất:

1. Thu thập các đầu vào có thẩm quyền
   • lược đồ, siêu dữ liệu PR, hoặc bản ghi (tốt nhất cho quy trình giao diện người dùng)
2. Nền tảng trước, tạo sau
   • truy xuất với trích dẫn, hoặc trích xuất xác định từ các nguồn có cấu trúc
3. Tạo bản nháp với “siêu dữ liệu xác minh”
   • chủ sở hữu, phiên bản xác minh cuối cùng, PR nguồn được liên kết, “bản nháp so với đã xác minh”
4. Chạy kiểm tra tự động
   • kiểm tra liên kết, kiểm tra phong cách, định dạng đoạn mã
5. Cổng kiểm soát theo rủi ro
   • tài liệu bên ngoài: đánh giá và quản lý phiên bản nghiêm ngặt hơn
   • tài liệu nội bộ: nhanh hơn, nhưng dán nhãn bản nháp rõ ràng
6. Xuất bản như mã
   • đánh giá PR, vượt qua CI, quyền sở hữu rõ ràng
7. Phát hiện sự trôi dạt
   • cảnh báo “những gì đã thay đổi” cho chủ sở hữu
   • đừng đợi các phiếu hỗ trợ trở thành hệ thống giám sát của bạn

Điều này cũng phù hợp với mục tiêu cốt lõi của kỹ thuật nền tảng: giảm tải nhận thức với các “con đường vàng” rõ ràng thay vì để mọi người tự mò mẫm qua kiến thức bộ lạc.

Những chiến thắng đầu tiên bạn có thể đạt được trong hai tuần#

Nếu bạn đang bắt đầu từ sự hỗn loạn, đừng thực hiện một “cuộc viết lại lớn”. Hãy thực hiện ba tự động hóa nhỏ mang lại hiệu quả tích lũy:

1. Tạo tài liệu tham khảo
   • lược đồ thành tài liệu, tạo lại mỗi lần phát hành
2. Phát hiện sự lỗi thời
   • chủ sở hữu + siêu dữ liệu “xác minh lần cuối so với”
3. Bản nháp nhật ký thay đổi
   • tự động soạn thảo, con người chỉnh sửa

Đây là những tự động hóa an toàn nhất với lợi ích “giảm thiểu phiếu hỗ trợ” nhanh nhất.

Hình ảnh chứng minh tài liệu của bạn là thật (không phải hình nền doanh nghiệp)#

Bỏ qua các ảnh chụp bắt tay. Hãy sử dụng bằng chứng:

• Ảnh chụp màn hình bảng điều khiển độ lệch hiển thị các trang “đã xác minh bản phát hành này” so với “không xác định”
  • Văn bản thay thế: “Bảng điều khiển trình tạo tài liệu AI hiển thị các trang trung tâm trợ giúp đã xác minh so với lỗi thời”
• Chuỗi ảnh chụp màn hình có chú thích (số + mũi tên) cho một bước quy trình làm việc
  • Văn bản thay thế: “Ghi màn hình sang đầu ra tài liệu với các bước được đánh số và các thành phần giao diện người dùng được làm nổi bật”
• Ảnh so sánh trước/sau của một tài liệu được cập nhật từ PR phát hành

Nếu bạn xuất bản hướng dẫn, hãy nhúng video phía trên bài viết để người dùng có thể chọn phong cách học tập ưa thích của họ. Clevera xuất chính xác định dạng này: video ở trên, bài viết từng bước ở dưới.

Bước tiếp theo của bạn#

Chọn một tài liệu mà khách hàng của bạn dựa vào trong tuần này.

Vẽ nhanh biểu đồ 2×2: sự mơ hồ so với phạm vi ảnh hưởng.
Sau đó, tự động hóa một phần an toàn (tài liệu tham khảo, phát hiện độ lệch hoặc tài liệu hướng dẫn dựa trên bản ghi) và đặt cổng kiểm duyệt cho phần rủi ro.

Nếu làm đúng, bạn sẽ không chỉ xuất bản nhanh hơn. Bạn sẽ ngủ ngon hơn.

Thử thách: Đâu là một tài liệu “trông có vẻ uy tín nhưng lại sai” trong sản phẩm của bạn hiện nay, và đầu vào nào sẽ làm cho nó có thể phát lại: lược đồ, bản diff PR hay bản ghi màn hình?