Dùng Claude viết tài liệu kỹ thuật từ GitHub README: bản nháp trong 10 phút
Bạn mở một repository GitHub, đọc hết README, nhưng vẫn chưa chắc phải cài gì, chạy lệnh nào và kiểm tra kết quả ở đâu. Người viết code hiểu dự án; người mới lại cần một lộ trình cụ thể. Khoảng trống đó chính là việc tài liệu kỹ thuật cần giải quyết.
Claude có thể giúp biến những tệp sẵn có thành một bản nháp dễ đọc trong khoảng 10 phút, nếu phạm vi đủ nhỏ và đầu vào đã được chuẩn bị. Phần cần thêm thời gian là chạy thử hướng dẫn, đối chiếu hành vi thật và nhờ người phụ trách dự án duyệt lại.
Trong bài này, chúng ta sẽ tạo một hướng dẫn bắt đầu sử dụng, kèm prompt có thể sao chép, cách kiểm chứng và cách duy trì cả bản Việt lẫn bản Anh.
🧭 1. Chọn đúng tài liệu cần viết
Đừng mở đầu bằng “hãy viết toàn bộ tài liệu cho repo này”. Một repository có thể phục vụ nhiều đối tượng: người dùng muốn chạy ứng dụng, lập trình viên muốn sửa code, hoặc đội vận hành muốn triển khai. Mỗi nhóm cần một đường đi khác nhau.
Hãy chốt ba điều trước khi gửi dữ liệu cho Claude:
- Người đọc: một lập trình viên mới tham gia dự án.
- Đích đến: chạy được ví dụ đầu tiên trong môi trường phát triển.
- Phạm vi: cài đặt, cấu hình, khởi chạy và xử lý các lỗi đã có bằng chứng.
Theo hướng dẫn README của GitHub, README giúp người đọc hiểu dự án và bắt đầu sử dụng. Bạn có thể giữ phần giới thiệu ngắn ở đây, rồi đặt hướng dẫn chi tiết trong thư mục docs/.
Mục tiêu tốt cho 10 phút: một bản nháp hướng dẫn bắt đầu, danh sách điểm chưa rõ và kế hoạch kiểm thử. Thời gian hoàn thiện phụ thuộc vào độ phức tạp của dự án.
📂 2. Phút 0–2: chuẩn bị bộ nguồn vừa đủ
README là điểm xuất phát, nhưng có thể đã cũ hoặc thiếu thông tin. Chọn thêm những tệp trực tiếp giúp trả lời câu hỏi “người mới phải làm gì để chạy được dự án?”.
README.md: mô tả, cách dùng và liên kết hiện có.- Tệp khai báo phụ thuộc, chẳng hạn
package.jsonhoặcpyproject.toml: thông tin phù hợp với hệ công nghệ của dự án. - Tệp khóa phụ thuộc và cấu hình runtime, nếu có: căn cứ để kiểm tra công cụ và phiên bản.
.env.example: tên biến cấu hình và giá trị mẫu, thay cho tệp.envchứa thông tin thật.- Tệp khởi động, ví dụ sử dụng hoặc bài kiểm thử liên quan: bằng chứng về cách gọi và kết quả mong đợi.
- Cấu hình CI,
CONTRIBUTING.mdvàLICENSE, nếu phần tài liệu cần đề cập đến chúng.
Chỉ gửi những tệp cần cho phạm vi đã chọn. Nếu viết hướng dẫn khởi chạy, bạn chưa cần đưa toàn bộ giao diện, tài nguyên ảnh và mã của mọi module vào cuộc trò chuyện.
Ghi lại nhánh và commit của bộ nguồn. Hai lệnh sau chỉ đọc thông tin trong một bản sao Git cục bộ:
git branch --show-current git rev-parse HEAD
Kèm mã commit trong lời nhắn để sau này biết tài liệu được đối chiếu với phiên bản nào. Nếu đang ở trạng thái detached HEAD, lệnh đầu có thể không trả tên nhánh; mã commit vẫn là thông tin hữu ích.
🔗 3. Đưa tệp vào Claude và kiểm tra khoảng trống
Nếu tài khoản của bạn đã bật tích hợp GitHub, có thể chọn + → Add from GitHub, rồi chọn các tệp cần đọc. Cách thiết lập và quyền truy cập được mô tả trong tài liệu chính thức của Claude.
Một cách khác là tải các tệp lên hoặc dán nội dung theo từng khối, ghi rõ tên tệp. Dù dùng cách nào, hãy yêu cầu Claude liệt kê các tệp thực sự đọc được; một đường link được gửi vào chat chưa đủ để chứng minh nội dung đã được nạp.
Phút 2–4 dành cho việc tìm chỗ thiếu, trước khi yêu cầu viết dài. Dùng prompt này và thay những phần trong ngoặc vuông:
Tôi cần một hướng dẫn bắt đầu cho [đối tượng đọc]. Mục tiêu: [việc cụ thể họ cần làm được]. Phạm vi: [phần cần viết]; ngoài phạm vi: [phần chưa viết]. Nguồn: [repository], nhánh [nhánh], commit [mã commit]. Trước khi viết, hãy: 1. Liệt kê các tệp bạn thực sự đọc được. 2. Tóm tắt quy trình khởi chạy được chứng minh bởi các tệp đó. 3. Chỉ ra mâu thuẫn giữa README, cấu hình và mã nguồn. 4. Liệt kê dữ liệu còn thiếu và tệp cần bổ sung. Với lệnh, phiên bản, biến môi trường và API, ghi rõ tệp làm căn cứ. Không suy đoán thông tin còn thiếu; đánh dấu [CẦN XÁC MINH]. Chưa viết tài liệu hoàn chỉnh ở bước này.
Nếu Claude phát hiện README dùng một lệnh nhưng manifest không có script tương ứng, hãy giải quyết mâu thuẫn trước. Một đoạn văn trôi chảy sẽ không sửa được một lệnh sai.
✍️ 4. Phút 4–7: yêu cầu bản nháp có thể kiểm tra
Khi đầu vào đã đủ, yêu cầu Claude viết theo trình tự người đọc sẽ thực hiện. Mỗi bước nên có mục đích, thao tác và dấu hiệu thành công. Nếu chưa có bằng chứng về dấu hiệu thành công, để lại điểm cần xác minh.
Dựa trên bộ nguồn và các điểm đã làm rõ, viết bản nháp Markdown cho docs/GETTING_STARTED.md bằng tiếng Việt. Cấu trúc: - Dự án làm gì và hướng dẫn này dành cho ai. - Điều kiện cần có, chỉ nêu phiên bản được nguồn xác nhận. - Cài đặt và cấu hình theo đúng thứ tự. - Chạy ví dụ đầu tiên và cách nhận biết kết quả đúng. - Các lỗi có bằng chứng: biểu hiện, nguyên nhân, cách xử lý. - Liên kết tới phần tài liệu liên quan đã tồn tại. Quy tắc: - Giữ nguyên tên lệnh, đường dẫn, biến môi trường và định danh API. - Không tự tạo script, endpoint, giá trị cấu hình hoặc kết quả chạy. - Không tuyên bố đã kiểm thử nếu chưa có log kiểm thử được cung cấp. - Đánh dấu [CẦN XÁC MINH] tại thông tin chưa đủ căn cứ. - Các giá trị mẫu phải được ghi rõ là ví dụ. - Không tự diễn giải thêm quyền cấp phép; dẫn tới LICENSE nếu có. Sau bản nháp, trả riêng: 1. Bản đồ thông tin quan trọng → tệp nguồn làm căn cứ. 2. Danh sách điểm cần xác minh trước khi công bố. 3. Kế hoạch kiểm tra từ một môi trường sạch.
Tách phần ghi chú dành cho người duyệt khỏi tài liệu dành cho người dùng. Bản đồ nguồn giúp bạn rà soát nhanh, nhưng không nhất thiết phải xuất hiện trong hướng dẫn cuối cùng.
💡 Một thay đổi nhỏ làm tài liệu hữu ích hơn
Câu “chạy ứng dụng sau khi cài đặt” bắt người đọc đoán bước tiếp theo. Hướng dẫn tốt hơn sẽ chỉ ra lệnh đã xác nhận từ dự án, thư mục cần đứng khi chạy, cấu hình cần có và cách kiểm tra ứng dụng đã sẵn sàng.
Độ cụ thể phải đến từ nguồn. Nếu chưa biết cổng mặc định, đừng để Claude tự điền một con số quen thuộc chỉ để hoàn thành đoạn văn.
🔍 5. Phút 7–10: rà soát và lập danh sách kiểm thử
Đọc bản nháp như một người chưa từng dùng dự án. Tìm những bước nhảy cóc: đã yêu cầu tạo cơ sở dữ liệu chưa, biến cấu hình lấy từ đâu, đường dẫn được tính từ thư mục nào?
Sau đó kiểm tra các nhóm sau. Với dự án lớn, phần chạy thử có thể kéo dài hơn khung 10 phút:
- Lệnh và phụ thuộc: lệnh có trong nguồn không, đúng công cụ quản lý gói không, điều kiện về phiên bản có căn cứ không?
- Thao tác thực tế: thực hiện hướng dẫn trên môi trường phù hợp, ghi lại đầu ra và bước thất bại.
- API và ví dụ: đối chiếu tên hàm, tham số, kiểu dữ liệu và kết quả với mã hoặc đặc tả liên quan.
- Liên kết: mở từng đường dẫn; xác nhận tệp và mục được trỏ tới tồn tại.
- Điểm còn thiếu: giải quyết mọi nhãn cần xác minh ảnh hưởng đến việc người đọc hoàn thành tác vụ.
Nếu một bước thất bại, gửi lại cho Claude lệnh đã chạy, thư mục làm việc, thông báo lỗi đã lược bỏ dữ liệu nhạy cảm và tệp liên quan. Yêu cầu sửa đúng mục có lỗi, rồi chạy lại phần bị ảnh hưởng.
AI viết nhanh; kết quả chạy thật quyết định hướng dẫn có dùng được hay không. Đừng đánh dấu “đã kiểm thử” chỉ vì Claude đọc lại và nói nội dung hợp lý.
🌐 6. Xuất bản cả tiếng Việt và tiếng Anh
Khi bản gốc đã được kiểm chứng, dùng nó làm nguồn cho bản dịch. Việc dịch cả hai bản từ cùng một bản nháp còn sai sẽ khiến bạn phải sửa hai lần.
Dịch bản hướng dẫn đã duyệt sang tiếng Anh. Giữ nguyên code block, lệnh, đường dẫn, tên tệp, biến môi trường, định danh API và giá trị cấu hình. Giữ nguyên mức độ chắc chắn: không đổi “có thể” thành “luôn luôn”. Không thêm tính năng, yêu cầu hệ thống hoặc bước triển khai mới. Cuối cùng liệt kê riêng các thuật ngữ cần người duyệt xác nhận.
Bạn có thể lưu hai bản trong docs/vi/ và docs/en/, hoặc chọn cấu trúc đang có của dự án. Kiểm tra lại liên kết tương đối sau khi di chuyển tệp: cùng một đường dẫn có thể trỏ sai khi thư mục thay đổi.
Nếu cần minh họa thao tác, hãy quay một lượt thực hiện đúng hướng dẫn đã duyệt. CYAN CAM đang ở giai đoạn beta, hỗ trợ quay màn hình và lưu MP4 cục bộ, phù hợp để chuẩn bị video hướng dẫn đi kèm. Video và bài viết nên thể hiện cùng một phiên bản ứng dụng.
🔄 7. Giữ tài liệu đi cùng thay đổi của code
Đưa thay đổi tài liệu lên một nhánh riêng và mở pull request để người hiểu dự án duyệt. Phần mô tả nên ghi rõ phạm vi, commit nguồn và những bước bạn đã thực sự chạy thử.
Ở lần cập nhật tiếp theo, cung cấp cho Claude tài liệu hiện tại cùng các tệp hoặc diff liên quan. Yêu cầu nó chỉ ra mục bị ảnh hưởng trước khi sửa, chẳng hạn lệnh khởi chạy đổi tên, một biến cấu hình được thêm hoặc ví dụ API không còn phù hợp.
Lưu một checklist ngắn trong quy trình review: code thay đổi có làm hướng dẫn cũ sai không, bản dịch đã được cập nhật chưa, video minh họa có cần quay lại không? Đây là cách tránh tình trạng tài liệu đẹp ở ngày đầu nhưng nhanh chóng trở nên khó dùng.
✅ Bắt đầu bằng một việc nhỏ hôm nay
Chọn một repo bạn hiểu, một README và một tác vụ cụ thể. Trong lượt đầu, tạo bản nháp hướng dẫn bắt đầu rồi ghi rõ phần nào đã có căn cứ, phần nào phải chạy thử. Sau khi kiểm chứng, bạn có thể áp dụng cùng cách làm cho hướng dẫn cấu hình, ví dụ API hoặc tài liệu đóng góp.
Giá trị của Claude nằm ở việc giúp bạn tổ chức và diễn đạt nhanh hơn. Giá trị của tài liệu nằm ở việc người khác làm theo và đạt được kết quả.