Cách mình viết Userguide cùng với AI

✍️ Hana · 🗓️ Tháng 5/2026 📚 Series: Làm Cùng với AI · BA Edition 🔢 Order: 13

Trang docs Redis Cluster trên GreenNode - kết quả của write-docs skill

---

Mình từng không thích viết doc

Thú thật là một thời gian dài, viết userguide là phần mình sợ nhất trong công việc BA. Không phải vì không biết viết - mà vì viết doc xong mới chỉ là bắt đầu.

Docs của VNG Cloud publish trên GitBook, repo có cấu trúc cụ thể: Vietnamese/[product]/[service]/[feature]/file-vi.md và English/[product]/[service]/[feature]/file-en.md song song nhau. Mỗi lần tạo file mới phải nhớ cập nhật SUMMARY.md - cả bản VI lẫn EN - nếu quên thì trang đó không có trong nav, publish lên GitBook cũng như không. Commit phải đúng branch huyettn3, push xong tạo PR lên main, GitBook mới sync được. Sai bất kỳ bước nào là phải quay lại fix.

Rồi còn chuyện song ngữ. VNG Cloud doc bắt buộc có cả tiếng Việt lẫn tiếng Anh. Viết xong file VI, mình phải dịch ra EN - và không phải dịch kiểu Google Translate, mà phải giữ nguyên cấu trúc heading từng section, UI label phải đúng tiếng Anh của product, technical term như Failover, Replica, Snapshot không được Việt hóa. Sau nhiều lần edit lại file VI, file EN bắt đầu drift - heading chênh nhau, có section ở VI nhưng thiếu EN, rồi lại fix từng cái.

Một lần mình viết docs cho Redis Cluster của vDB: 4 files cần tạo - một concept page, hai how-to guide, một reference page - cộng với SUMMARY.md cả hai ngôn ngữ. Nếu làm thủ công chắc mất hơn hai ngày. Phần lớn thời gian không phải là nghĩ nội dung, mà là nhớ đúng folder path, đúng branch, đúng convention.

Bây giờ với skill write-docs, tất cả cái đó AI lo. Mình chỉ cần review và nói "ok".

---

write-docs skill là gì

Skill này là bộ instruction mình viết để AI biết cách tạo docs theo đúng chuẩn VNG Cloud - từ folder structure, naming convention, cho đến từng quy tắc nhỏ như "service name phải viết vDB không phải VDB", "UI label giữ nguyên tiếng Anh", "hint block warning chỉ dùng cho destructive action".

Workflow từ đầu đến cuối:

Workflow của write-docs skill

Hai điểm quan trọng trong workflow này là HARD STOP trước khi commit - AI không bao giờ tự push code lên repo mà không có approval - và checklist 12 tiêu chí chạy tự động trước khi present kết quả cho mình.

---

Ba điểm mình thích nhất khi dùng

1. Paste PRD vào - AI tự biết cần viết loại doc gì

Cái này mình thích nhất. Không cần nói "viết concept page" hay "viết how-to guide" - mình chỉ paste PRD hoặc dev spec vào và hỏi "viết doc cho cái này". AI đọc input rồi tự detect:

Với Redis Cluster, mình paste PRD vào - AI trả về: một concept page giải thích kiến trúc Master/Replica, hai how-to guide (tạo cluster + thêm Read Replica), một reference page cho các tham số config. Đúng 4 files cần. Không thiếu, không thừa.

2. Bilingual tự động - file EN không còn bị drift khỏi VI

Vấn đề lớn nhất khi viết song ngữ thủ công là drift: sau nhiều lần sửa file VI, file EN bắt đầu lệch ra. Heading không khớp, có section trong VI nhưng thiếu EN, hoặc ngược lại.

Skill xử lý chuyện này bằng cách viết EN ngay sau VI trong cùng một lần - và có quy tắc cứng: "EN file must have identical headings in identical order to VI file." Nếu mình sau đó sửa file VI, mình biết cần update EN theo đúng section tương ứng vì structure đã được định nghĩa từ đầu.

Một điểm nhỏ nhưng hay: skill có file conventions.md với danh sách term không được dịch (Replica, Failover, Snapshot, Namespace, Ingress...) và casing chuẩn của từng service (vDB không phải VDB, vMonitor không phải Vmonitor). AI đọc file này trước khi viết, nên output ra không có lỗi convention - cái mình hay bị comment trong PR review trước đây.

3. Approval gate + PR flow - không bao giờ push thẳng lên production

Đây là điểm thiết kế mình tôn trọng nhất. Skill có một HARD STOP sau khi viết xong: AI present summary, liệt kê file sẽ tạo, chờ mình nói "ok" hoặc "stop" - không tự commit gì cả.

Khi mình approve, AI mới chạy đúng flow:

1. git checkout huyettn3 → git pull origin main (sync branch trước)
2. git add [specific files] — không dùng git add . để tránh commit nhầm
3. Commit message đúng format: [docs] [Product] [Feature] — VI + EN
4. Push lên huyettn3 → tạo PR lên main
5. Trả về link PR + GitBook URLs draft (live sau khi merge)

Mình không merge thay. GitBook chỉ sync sau khi mình tự merge PR vào main.

Cái flow này quan trọng vì trước đây mình hay tự commit tắt cho nhanh, đôi khi push nhầm cả file draft chưa xong lên main. Giờ AI làm đúng quy trình hơn mình ngày trước.

---

Kết quả thật — Redis Cluster docs

Đây là session Redis Cluster mình nhắc từ đầu bài. Input: PRD PostgreSQL Cluster (feature có Backup flow tích hợp). Output AI tạo ra:

Vietnamese/vdb/memorystore-database-service-mds/redis-cluster/
├── redis-cluster.md                ← concept page (kiến trúc, use case)
├── khoi-tao-redis-cluster.md       ← how-to guide (tạo cluster)
└── them-read-replica.md            ← how-to guide (thêm replica)

English/vdb/memorystore-database-service-mds/redis-cluster/
├── redis-cluster.md
├── create-redis-cluster.md
└── add-read-replica.md

+ SUMMARY.md diff (VI + EN)
+ Release note entry cho tháng tương ứng

Tổng: 437 dòng VI output. Bilingual. Folder structure đúng. Convention đúng. SUMMARY.md đã có diff để paste vào.

Mình dành thời gian còn lại của buổi đó để review nội dung - đọc từng step trong how-to guide, check xem sequence có đúng với flow thật trên portal không. Đó mới là việc của BA. Còn phần cấu trúc, naming, song ngữ - AI lo hết.

---

Một điều mình vẫn làm thủ công

Content accuracy vẫn là của mình, và không có cách nào khác.

Skill viết đúng cấu trúc, đúng convention, đúng ngôn ngữ - nhưng không biết UI thật trên portal trông như thế nào. Các bước trong how-to guide AI đề xuất dựa trên PRD, không phải dựa trên product đang chạy production. Label button có thể đã đổi từ sprint trước. Một bước mới có thể vừa được dev thêm vào nhưng chưa update PRD.

Mình luôn mở portal thật và click thử từng bước trước khi approve commit. Thường tìm thấy 2-3 chỗ cần sửa nhỏ. Đó không phải là AI sai — đó là gap tự nhiên giữa PRD và product thật. BA là người cầu nối cái gap đó, không phải AI.

---

Một câu để đọng lại

Trước kia mình viết doc xong mới lo folder path, branch, convention. Giờ AI lo hết mấy cái đó để mình tập trung vào một thứ duy nhất: nội dung có đúng với product thật không.

Lần gần nhất bạn commit doc nhầm branch, hoặc publish lên GitBook rồi mới thấy SUMMARY.md chưa cập nhật - đó không phải lỗi của bạn, đó là lỗi của một quy trình không có checklist. Skill không làm bạn viết hay hơn. Nó làm bạn không bao giờ quên SUMMARY.md nữa.

---

Bài này thuộc series "Làm Cùng với AI · BA Edition". Các bài tiếp theo: Cách mình viết PRD cùng với AI · Cách mình họp cùng AI · Cách mình chạy workflow bằng skill