Bạn sẽ viết README thế nào để một người mới vào dự án có thể chạy được nó, và bạn kiểm tra điều đó ra sao?

Người phỏng vấn muốn xem bạn có nghĩ về người đọc sau mình không, và bạn có biết cách kiểm tra tài liệu thay vì tin rằng nó đúng.

Một README đủ dùng trả lời bốn câu theo thứ tự: cần có gì trên máy (phiên bản Node, công cụ khác, kèm lý do), gõ lệnh nào để chạy lần đầu, thấy gì thì biết là chạy đúng, và gặp lỗi phổ biến thì làm gì. Phần "thấy gì là đúng" hay bị thiếu nhất, nhưng thiếu nó thì người mới không phân biệt được "đang chạy" với "chạy sai mà không báo". Phần "gặp lỗi" nên viết từ lỗi có thật bạn đã gặp khi chạy thử, không đoán.

Hai thủ thuật đáng nhắc. Thứ nhất, nếu một bước là "mở file này, sao chép, điền giá trị", hãy thay bằng một lệnh làm giúp (ví dụ npm run setup tạo .env và điền khóa ngẫu nhiên), vì ít bước làm tay thì ít chỗ sai. Thứ hai, đừng chép lại thứ có nguồn khác: danh sách biến môi trường nên trỏ tới .env.example, vì hai nơi cùng liệt kê một thứ sớm muộn sẽ lệch nhau.

Cách kiểm tra là làm theo README trong một thư mục trống, như vừa clone (không có node_modules, không có .env), tốt nhất bởi một người chưa biết dự án. Bạn cũng có thể viết script chạy các lệnh trong README và báo bước nào hỏng, nhưng script chỉ trả lời được "máy có làm theo được không", không trả lời được "người có hiểu không".

Điểm cộng: nói được README sẽ cũ đi khi code đổi, và bạn có thể kiểm tự động việc đường dẫn và tên script nó nhắc tới còn tồn tại.