Docs-as-Code cheat sheet — một trang tóm tắt toàn bộ

Một trang. In ra dán lên tường. Nếu cả đội chỉ nhớ một thứ về docs-as-code, hãy để nó là trang này.

Suốt loạt bài docs-as-code, ý tưởng lặp đi lặp lại chỉ có một: coi tài liệu như mã nguồn — plain text, để trong version control, review qua pull request, và để CI tự kiểm tra. Bốn thói quen đó khoá thành một vòng; bỏ một mắt là tài liệu bắt đầu rot (mục ruỗng) trở lại.

Tấm cheat sheet dưới đây nén cả vòng đó vào một trang: bốn thói quen cốt lõi, ba cái bẫy khiến tài liệu vẫn thất bại dù đã "as-code", và cấu trúc repo theo golden thread — sợi chỉ vàng nối BRD → thiết kế → contract → code → test để mọi thay đổi đều truy ngược được.

Dùng trang này thế nào

• Đội mới bắt đầu: dán lên wiki, lấy làm "định nghĩa xong" (definition of done) cho mọi tài liệu — đủ 4 thói quen mới coi là đạt.
• Review pull request: mỗi khi đổi code chạm API/contract, hỏi đúng ba câu trong phần "cái bẫy" — tài liệu đã đi cùng PR chưa, contract đã cập nhật chưa, test đã phản ánh chưa.
• Onboard người mới: đây là 3 phút đầu tiên — hiểu được trang này là hiểu được vì sao đội viết tài liệu theo cách này.

Cheat sheet này thuộc bộ giáo cụ mã nguồn mở docs-as-code-kit (CC BY 4.0) tôi đang xây — dạy docs-as-code qua một super-app hư cấu "NovaApp", có đủ bài học, ví dụ chạy được, và bản tiếng Anh. Tải về hoặc cài làm plugin Claude Code tại GitHub: leduykhuong-daniel/OSS-docs-as-code-kit.