AI viết tài liệu cho mã rất nhanh, nhưng nó chỉ thấy mã làm gì chứ không biết vì sao mã được viết như vậy, ai sẽ đọc tài liệu và họ cần làm gì. Câu lệnh tốt cho việc viết tài liệu vì vậy phải đưa ba thứ đó vào: lý do của các quyết định quan trọng, người đọc là ai, và việc họ cần làm được sau khi đọc. Sau đó, mọi lệnh và bước trong tài liệu phải được chạy thử thật.
Bài này đi qua bốn loại tài liệu hay nhờ AI viết nhất: chú thích cho hàm, tệp README, hướng dẫn cài đặt và nhật ký thay đổi kèm thông điệp lưu thay đổi. Mỗi loại có mẫu câu lệnh và chỗ cần kiểm riêng.
Mã nói "làm gì", tài liệu tốt nói "vì sao"
Đưa một hàm cho trợ lý và yêu cầu "viết chú thích", bạn thường nhận về một đoạn mô tả lại mã bằng lời: hàm nhận danh sách đơn hàng, lặp qua từng đơn, cộng tổng tiền, trả về kết quả. Đoạn đó đúng nhưng ít giá trị, vì người đọc mã cũng thấy điều đó trong mười giây. Thông tin người đọc thật sự cần là những thứ không có trong mã: vì sao loại đơn có trạng thái chờ đối soát, vì sao làm tròn ở bước này chứ không ở bước sau, giới hạn nào đã biết mà chưa xử lý.
Trợ lý không thể suy ra những điều đó, trừ khi bạn nói. Vì vậy câu lệnh viết tài liệu cần một phần mà người ta hay bỏ: các ghi chú thô của bạn về lý do. Viết lộn xộn cũng được — "loại đơn chờ đối soát vì cổng thanh toán đôi khi báo trễ, kế toán yêu cầu" — trợ lý sẽ biến nó thành câu gọn. Phần việc của nó là diễn đạt; phần việc của bạn là cung cấp sự thật.
Ngược lại, chú thích kiểu "tăng biến đếm lên một" trên dòng tăng biến đếm là nhiễu. Dặn rõ trong câu lệnh: không chú thích những dòng tự giải thích được.
Chọn đúng kiểu chú thích theo ngôn ngữ
Mỗi hệ sinh thái có quy ước chú thích hàm riêng, và công cụ sinh tài liệu hoặc trình soạn thảo đọc được quy ước đó. Nói rõ quy ước dự án đang dùng để trợ lý không tự chọn.
| Ngôn ngữ | Quy ước phổ biến | Lưu ý khi giao việc |
|---|---|---|
| Python | Docstring theo kiểu Google, NumPy hoặc reStructuredText | Chỉ định một kiểu; trộn nhiều kiểu trong một dự án làm công cụ sinh tài liệu đọc sai |
| JavaScript | Chú thích JSDoc với các thẻ tham số và giá trị trả về | Nếu dự án dùng TypeScript, kiểu đã nằm trong chữ ký, chú thích nên tập trung vào ý nghĩa |
| TypeScript | TSDoc hoặc JSDoc rút gọn | Dặn không lặp lại kiểu đã khai trong chữ ký |
| PHP | PHPDoc với các thẻ tham số, trả về, ngoại lệ | Thẻ ngoại lệ thường bị thiếu; yêu cầu liệt kê các lỗi hàm có thể ném |
| SQL | Chú thích dòng trong tệp chuyển đổi lược đồ | Ghi lý do của thay đổi và cách quay lui |
Ngôn ngữ viết chú thích — tiếng Việt hay tiếng Anh — cũng là quy ước cần nói. Đội toàn người Việt, dự án nội bộ thường viết tiếng Việt cho dễ đọc; dự án mã nguồn mở hay có người nước ngoài tham gia thường dùng tiếng Anh. Quan trọng là thống nhất trong cùng dự án.
Mẫu câu lệnh viết chú thích cho một hàm
Bài toán giả định: hàm tính tiền hoàn cho đơn trả hàng.
- "Viết docstring kiểu Google, bằng tiếng Việt, cho hàm sau: [dán hàm]."
- "Người đọc: lập trình viên khác trong nhóm sẽ sửa hàm này sau vài tháng."
- "Lý do cần ghi vào: [hoàn tiền không gồm phí giao vì quy định cửa hàng; đơn quá ba mươi ngày trả về 0 thay vì ném lỗi vì màn hình hiện thông báo riêng]."
- "Ghi rõ: ý nghĩa từng tham số và đơn vị, giá trị trả về, các trường hợp đặc biệt, lỗi có thể ném."
- "Không mô tả lại từng dòng mã. Không thêm chú thích vào thân hàm trừ chỗ có logic không hiển nhiên."
Đọc lại chú thích nhận về với một câu hỏi: có câu nào nói điều mà mã không làm không? Trợ lý đôi khi viết "hàm kiểm tra đơn tồn tại trước khi tính" trong khi thân hàm không hề kiểm. Chú thích sai còn hại hơn không có chú thích, vì người đọc sau sẽ tin nó.
Tệp README: viết cho người lần đầu mở dự án
Bắt đầu bằng một đoạn trả lời "đây là gì, để làm gì". Hai đến ba câu, không tiếp thị. Người đọc cần biết họ có đang mở đúng dự án không.
Cài đặt và chạy lần đầu. Danh sách phần mềm cần có kèm phiên bản, các bước cài, lệnh chạy, và kết quả mong đợi khi chạy thành công. Đây là phần dễ sai nhất, sẽ bàn riêng ở mục sau.
Cấu hình. Các biến môi trường cần đặt, mỗi biến một dòng mô tả và giá trị mẫu giả. Không bao giờ để khoá thật trong README, kể cả kho mã riêng tư.
Cấu trúc thư mục ở mức thô. Năm đến mười dòng nói thư mục nào chứa gì. Trợ lý làm phần này tốt nếu bạn đưa danh sách thư mục.
Cách chạy kiểm thử và cách đóng góp. Lệnh chạy kiểm thử, quy ước nhánh, nơi báo lỗi.
Câu lệnh mẫu. Đưa cho trợ lý danh sách thư mục, tệp cấu hình mẫu, các lệnh bạn thật sự dùng hằng ngày, và yêu cầu: "Viết README theo các mục trên, chỉ dựa trên thông tin đã đưa, chỗ nào thiếu thông tin thì để dòng ghi CẦN BỔ SUNG thay vì tự điền." Câu cuối chặn việc trợ lý bịa ra lệnh cài hay tính năng nghe hợp lý.
Hướng dẫn cài đặt: phải chạy thử trên máy sạch
Hướng dẫn cài do AI viết thường trông chuẩn chỉnh, nhưng hay có lệnh sai tên gói, thiếu một bước người viết đã làm từ lâu trên máy mình, hoặc thứ tự không đúng. Cách duy nhất để chắc là làm theo đúng từng chữ:
- Dựng một môi trường sạch: máy ảo, vùng chứa, hoặc một tài khoản người dùng mới trên máy.
- Làm theo hướng dẫn từng bước, chỉ gõ đúng những gì được viết, không dùng kiến thức sẵn có để "tự hiểu".
- Mỗi chỗ bị kẹt, ghi lại bước, lỗi và cách bạn đã gỡ.
- Đưa danh sách chỗ kẹt cho trợ lý, yêu cầu sửa hướng dẫn cho đúng các điểm đó, không viết lại phần đã chạy được.
- Lặp lại trên môi trường sạch mới cho tới khi đi hết mà không kẹt.
Nếu dự án có người dùng máy khác hệ điều hành, ít nhất một người trong nhóm nên thử trên hệ điều hành đó. Lệnh chạy được trên Linux có thể khác trên Windows ở cách đặt biến môi trường hay đường dẫn tệp.
Nhật ký thay đổi và thông điệp lưu thay đổi
Trợ lý trong trình soạn thảo và tác tử dòng lệnh thường đề xuất được thông điệp lưu thay đổi từ phần khác biệt của mã. Thông điệp đó thường mô tả đúng cái gì đã đổi, nhưng ít khi nói vì sao — lại chính là phần người đọc lịch sử sau này cần. Một thói quen tốt là để trợ lý viết dòng tiêu đề, rồi tự thêm một câu lý do ngắn hoặc mã việc liên quan.
Với nhật ký thay đổi gửi cho người dùng hay khách hàng, có thể đưa cho trợ lý danh sách thông điệp lưu thay đổi giữa hai phiên bản và yêu cầu: "Gom thành nhật ký thay đổi cho người dùng không chuyên kỹ thuật: tính năng mới, lỗi đã sửa, thay đổi cần chú ý. Bỏ các thay đổi nội bộ không ảnh hưởng người dùng. Không thêm mục nào không có trong danh sách." Câu cuối lại là chốt chống bịa.
Đọc lại bản nhật ký với một câu hỏi: người dùng đọc xong có hiểu phải làm gì khác không. Một mục như "cải thiện hiệu năng" không giúp ai; "trang danh sách đơn hàng tải nhanh hơn khi có nhiều đơn" thì có.
Những câu lệnh kém hay gặp khi nhờ viết tài liệu
Chỉ nói "viết tài liệu cho dự án này". Không có người đọc, không có mục đích, trợ lý sẽ viết một README chung chung với các mục mặc định, phần nào thiếu thông tin thì tự điền cho đủ. Kết quả dài, trông chuyên nghiệp, và chứa những lệnh không ai từng chạy.
Dán cả kho mã rồi bảo tóm tắt. Trợ lý sẽ mô tả cấu trúc tệp khá đúng nhưng nhầm vai trò của các thành phần, nhất là khi tên tệp không nói rõ chức năng. Đưa kèm vài dòng của chính bạn về luồng chạy chính, để trợ lý có khung mà bám vào.
Yêu cầu "viết cho chuyên nghiệp". Câu này thường cho ra văn phong trang trọng, dài, nhiều tính từ. Tài liệu kỹ thuật tốt thì ngắn, cụ thể, mỗi câu một thông tin. Thay bằng yêu cầu cụ thể: câu ngắn, dùng danh sách cho các bước, không tính từ đánh giá.
Không nói phiên bản. Tài liệu ghi "cài phiên bản mới nhất" sẽ sai sau vài tháng. Yêu cầu ghi rõ phiên bản đã thử và câu "phiên bản khác có thể cần điều chỉnh".
Giữ tài liệu khỏi lệch với mã
Tài liệu viết một lần rồi để đó sẽ lệch dần với mã, và tài liệu lệch là bẫy cho người mới. AI làm việc cập nhật tài liệu rẻ hơn nhiều, nên đáng biến nó thành một bước trong quy trình: mỗi khi thay đổi chạm tới hàm công khai, cấu hình hay cách cài đặt, yêu cầu trợ lý chỉ ra những đoạn tài liệu cần sửa theo.
Một câu lệnh cho việc này: "Đây là phần khác biệt của thay đổi và tệp README hiện tại. Đoạn nào trong README không còn đúng sau thay đổi? Chỉ liệt kê và đề xuất sửa, không viết lại cả tệp." Người rà mã có thể thêm việc kiểm tài liệu vào danh sách rà soát. Phần tài liệu dự án dành cho cả tác tử AI lẫn người mới cùng đọc được bàn kỹ ở danh mục tác tử và làm việc nhóm của trang.
Câu hỏi thường gặp
Có nên để AI tự sinh chú thích cho toàn bộ dự án cũ không có tài liệu?
Có thể làm cho các hàm công khai quan trọng, nhưng đừng làm hàng loạt rồi lưu ngay. Chú thích sinh hàng loạt thường mô tả lại mã và đôi khi sai. Làm theo từng mô-đun, có người hiểu mô-đun đó đọc duyệt và bổ sung lý do.
Tài liệu nên viết tiếng Việt hay tiếng Anh?
Tuỳ người đọc. Đội nội bộ toàn người Việt thì tiếng Việt giúp đọc nhanh và chính xác hơn. Dự án có đối tác nước ngoài hoặc mã nguồn mở thì tiếng Anh phổ biến hơn. Trợ lý dịch qua lại khá tốt, nhưng thuật ngữ chuyên ngành nên thống nhất bằng một bảng thuật ngữ nhỏ.
AI có viết được sơ đồ kiến trúc cho tài liệu không?
Nhiều trợ lý viết được sơ đồ dưới dạng văn bản theo các cú pháp vẽ sơ đồ phổ biến, công cụ hiển thị tài liệu sẽ vẽ ra hình. Sơ đồ này cũng phải được người hiểu hệ thống duyệt, vì trợ lý dễ vẽ thêm mũi tên giữa các thành phần không thật sự gọi nhau.
Có nên dán mã nguồn công ty vào chatbot để nhờ viết tài liệu không?
Làm theo quy định của công ty về công cụ AI được phép. Nếu chưa có quy định, hỏi người phụ trách trước. Khi được phép, vẫn xoá khoá, mật khẩu, địa chỉ máy chủ nội bộ và dữ liệu thật trước khi dán.
Tài liệu API cho bên thứ ba có nên nhờ AI viết hết không?
Nhờ AI viết bản nháp từ đặc tả và mã là hợp lý, nhưng mọi ví dụ gọi API trong tài liệu phải được chạy thử thật trên môi trường thử. Bên thứ ba sẽ sao chép nguyên ví dụ; một ví dụ sai tham số tạo ra rất nhiều câu hỏi hỗ trợ.