Viết README, Issue và PR: Hỗ trợ cộng tác Open Source

Nhiều lập trình viên gặp phải thách thức tương tự khi đóng góp vào GitHub lần đầu tiên: mã hoạt động hoàn hảo, nhưng khi viết README, gửi Issue, hoặc tạo PR bằng tiếng Anh, luôn cảm thấy không đúng cách. Bạn lo lắng rằng người khác có thể không hiểu những gì bạn muốn nói.

Điều này hoàn toàn bình thường. Tiếng Anh kỹ thuật khác với tiếng Anh hàng ngày—nó có những quy ước và cụm từ riêng. Tin tốt là, khi bạn nắm vững một vài mẫu cơ bản, việc viết những tài liệu này dễ hơn bạn nghĩ rất nhiều.

Mục Lục

1. README: Giúp người khác nhanh chóng hiểu dự án của bạn
2. Issue: Mô tả chính xác vấn đề và yêu cầu
3. PR: Giải thích rõ ràng sự thay đổi của bạn
4. Làm cho tiếng Anh của bạn tự nhiên hơn
5. Thực hành tốt nhất
6. Cạm bẫy thường gặp
7. Mẹo hiệu suất
8. Khắc phục sự cố
9. FAQ

README: Giúp người khác nhanh chóng hiểu dự án của bạn

README là cửa sổ đầu tiên mà người khác nhìn vào dự án của bạn. Một README rõ ràng thường sắp xếp thông tin theo thứ tự sau: giải thích dự án làm gì, cho thấy cách sử dụng nó, và cung cấp bất kỳ thông tin hữu ích nào khác.

Mô tả dự án nên đơn giản và dễ hiểu. Ví dụ, "Dự án này giúp bạn quản lý các nhiệm vụ hàng ngày hiệu quả hơn" thì tốt hơn là "Đây là một công cụ quản lý nhiệm vụ tuyệt vời." Câu đầu tiên giải thích rõ ràng mục đích, trong khi câu thứ hai chỉ mang tính tự khen.

Tiếp theo, hướng dẫn cài đặt và sử dụng là rất quan trọng. Viết chúng từ góc độ của người không biết gì về dự án của bạn. Mỗi bước cần phải rõ ràng và chính xác—đừng bỏ qua bất kỳ bước nào tưởng như “hiển nhiên.” Ví dụ, khi cài đặt các phụ thuộc, bạn có thể viết, "Cài đặt các phụ thuộc bằng cách chạy npm install," thay vì chỉ viết "Cài đặt các phụ thuộc."

Ví dụ mã cũng quan trọng không kém. Một ví dụ tốt nên đầy đủ và có thể chạy được, mà không yêu cầu người đọc phải đoán các phần thiếu. Ví dụ, khi minh họa một cuộc gọi API, bao gồm các câu lệnh import, khởi tạo, và cuộc gọi thực tế.

Issue: Mô tả chính xác vấn đề và yêu cầu

Khi viết một Issue, điều quan trọng nhất là để các maintainer nhanh chóng hiểu vấn đề hoặc yêu cầu tính năng. Một sai lầm phổ biến là quá ngắn gọn, ví dụ, chỉ viết, "Nó không hoạt động." Những mô tả như vậy không hữu ích.

Khi báo cáo một lỗi, tổ chức thông tin theo thứ tự "triệu chứng–hành vi mong đợi–môi trường". Đầu tiên, mô tả vấn đề bạn quan sát được, sau đó nêu rõ những gì bạn mong đợi, và cuối cùng cung cấp chi tiết về môi trường của bạn. Ví dụ:
"Khi tôi nhấn nút gửi, trang hiển thị lỗi 500. Tôi mong đợi form được gửi thành công. Tôi đang sử dụng Chrome 91 trên macOS 12.1."

Nếu có thể, hãy cung cấp một ví dụ tái sản xuất tối thiểu. Điều này giúp các maintainer nhanh chóng xác định vấn đề và cho thấy rằng bạn đã dành thời gian để điều tra nó.

Khi yêu cầu một tính năng mới, hãy giải thích lý do bạn cần nó thay vì chỉ nêu điều bạn muốn. Ví dụ:
"Tôi thường cần xóa hàng loạt nhiều mục, nhưng hiện tại tôi phải xóa từng cái một, điều này rất tốn thời gian" thì tốt hơn là
"Xin vui lòng thêm tính năng xóa hàng loạt."

PR: Giải thích rõ ràng sự thay đổi của bạn

Một Pull Request là cách chính thức để đóng góp mã, vì vậy mô tả của bạn cần thêm sự chú ý. Một mô tả PR tốt nên giúp người đánh giá hiểu ba điều: bạn đã thay đổi cái gì, tại sao bạn thay đổi nó, và liệu sự thay đổi đó có an toàn không.

Tiêu đề nên ngắn gọn nhưng thông tin. "Sửa lỗi đăng nhập người dùng" thì tốt hơn là "Sửa lỗi," và "Thêm xác thực email vào đăng ký người dùng" thì tốt hơn là "Cập nhật user.js." Tiêu đề nên truyền tải rõ ràng mục đích chính của PR.

Trong phần nội dung, bắt đầu với ngữ cảnh. Vấn đề nào đã thúc đẩy sự thay đổi này? Nếu sửa lỗi, hãy mô tả hành vi của nó một cách ngắn gọn; nếu thêm tính năng, hãy giải thích trường hợp sử dụng. Sau đó, chi tiết giải pháp của bạn, và nếu bạn đã cân nhắc nhiều phương pháp, hãy đề cập lý do bạn chọn phương pháp hiện tại.

Thông tin kiểm tra cũng quan trọng. Giải thích cách bạn đã xác minh sự thay đổi của mình. Ví dụ:
"Tôi đã kiểm tra sự thay đổi này bằng cách tạo một người dùng mới với địa chỉ email không hợp lệ và xác nhận rằng lỗi xác thực được hiển thị đúng cách."

Làm cho tiếng Anh của bạn tự nhiên hơn

Có một vài mẹo để làm cho viết tiếng Anh của bạn trôi chảy hơn.

Đầu tiên, chú ý đến thì. Sử dụng thì hiện tại cho hành vi hiện tại, ví dụ, "Hàm này trả về email của người dùng"; thì quá khứ cho những thay đổi bạn đã thực hiện, ví dụ, "Tôi đã thêm xác thực cho trường email"; và thì tương lai hoặc động từ khiếm khuyết cho các hiệu ứng mong đợi, ví dụ, "Sự thay đổi này sẽ ngăn chặn email không hợp lệ" hoặc "Người dùng sẽ không còn thấy thông báo lỗi nữa."

Thứ hai, chú ý đến tông. Trong các môi trường mã nguồn mở như GitHub, lịch sự nhưng trực tiếp là tốt nhất. Bạn không cần phải xin lỗi quá nhiều (ví dụ, "Tôi xin lỗi đã làm phiền bạn, nhưng..."), nhưng cũng tránh âm thanh quá gay gắt. "Bạn có thể giúp tôi hiểu tại sao..." thì tốt hơn là "Tôi không hiểu tại sao..."

Cuối cùng, sử dụng các cụm từ phổ biến. Ví dụ:

• Để mô tả một vấn đề: "Tôi đang gặp phải một vấn đề mà..."
• Để yêu cầu giúp đỡ: "Tôi rất trân trọng bất kỳ hướng dẫn nào về..."
• Để giải thích sự thay đổi: "PR này giải quyết vấn đề bằng cách..."

Sử dụng những cụm từ này nhiều lần sẽ giúp chúng trở thành thói quen. Cuối cùng, bạn sẽ tự nhiên viết các tài liệu kỹ thuật rõ ràng và chính xác. Hãy nhớ, tiếng Anh hoàn hảo không phải là mục tiêu—chìa khóa là làm cho ý tưởng của bạn có thể hiểu được đối với người khác.

Thực hành tốt nhất

• Sử dụng ngôn ngữ đơn giản: Tránh các thuật ngữ phức tạp mà không cần thiết.
• Kiểm tra độ chính xác: Đảm bảo rằng thông tin trong README, Issue và PR là chính xác và cập nhật.
• Đọc lại: Hãy đọc lại tài liệu của bạn trước khi gửi để tìm lỗi chính tả và ngữ pháp.

Cạm bẫy thường gặp

• Thiếu thông tin: Không cung cấp đủ thông tin trong Issue hoặc PR.
• Mô tả không rõ ràng: Việc mô tả vấn đề hoặc thay đổi một cách mập mờ.
• Bỏ qua điểm kiểm tra: Không bao gồm thông tin kiểm tra cho các thay đổi.

Mẹo hiệu suất

• Sử dụng công cụ kiểm tra ngữ pháp: Các công cụ như Grammarly có thể giúp bạn cải thiện văn bản của mình.
• Thực hành thường xuyên: Viết thường xuyên sẽ giúp bạn cải thiện kỹ năng.

Khắc phục sự cố

• Tìm kiếm sự trợ giúp: Nếu bạn gặp khó khăn, đừng ngần ngại yêu cầu sự giúp đỡ từ cộng đồng.
• Kiểm tra các tài liệu khác: Nhiều dự án có tài liệu và ví dụ giúp bạn hiểu rõ hơn về cách viết README, Issue và PR.

FAQ

Q: Tôi có cần phải viết README bằng tiếng Anh không?
A: Nếu dự án của bạn hướng đến cộng đồng quốc tế, việc viết README bằng tiếng Anh là cần thiết.

Q: Làm thế nào để tôi biết liệu mô tả của mình có rõ ràng không?
A: Hãy nhờ một người khác đọc và cho phản hồi về mô tả của bạn.

Q: Tôi có thể sử dụng các mẫu có sẵn không?
A: Có, nhiều dự án cung cấp mẫu README, Issue và PR mà bạn có thể tham khảo.

Hy vọng với những hướng dẫn này, việc viết README, Issue và PR sẽ trở nên dễ dàng và hiệu quả hơn, giúp bạn và cộng đồng cùng nhau phát triển.