Làm thế nào để viết được một file README tốt?

Làm thế nào để viết được một file README tốt?

Tin ngắn hàng ngày dành cho bạn
  • Đúng là cái gì các pháp sư cũng nghĩ ra được. awk là một lệnh rất mạnh để xử lý tệp tin, nó có thể đọc, tìm, tổng hợp... dữ liệu văn bản. Đặc biệt là các tệp ghi logs hệ thống thì cứ phải gọi nó bằng... lệnh.

    jgarzik/sqawk đưa cách sử dụng awk lên "tầm cao mới". Áp dụng cú pháp SQL để truy vấn luôn 😆.

    » Xem thêm
  • Telegram chính thức không vào được nữa rồi, nếu công việc của bạn cần phải có Telegram thì hãy thử cách tạo ra một Proxy theo chuẩn MTProxy của Telegam tạo ra nhé. Mình tìm thấy một bài hướng dẫn rất chi tiết về cách làm ở đây. Đại loại là cần một máy chủ rồi gõ vài dòng lệnh là xong rồi 👇

    À, hiện có nhiều bài đăng chia sẻ Proxy miễn phí thì hãy cân nhắc trước khi sử dụng vì tiềm ẩn rủi ro bảo mật lắm đấy.

    How to set up a Telegram Proxy (MTProxy)

    » Xem thêm
  • Quên mất hôm trước có bảo chia sẻ cảm nghĩ cho mọi người khi chuyển sang dùng trình duyệt Safari thì chỉ sau 2 hôm mình đã phải quay trở lại Chrome mọi người ạ. Tại sao?

    Đầu tiên xin phép nêu ra một vài điểm mình thích ở Safari đó là giao diện của nó hết sức đơn giản, đúng nghĩa tập trung vào duyệt web thật sự, tốc độ thì thấy không thua kém gì Chrome. Ngoài ra một tính năng mà mình rất thích đó là cho "bay màu" một số thành phần bạn không thích trên một trang web nào đó. Tính năng đó gọi là Hide Distracting Items.

    Sau đó mình bắt đầu phát hiện ra một số bất cập khi mở Dev Tools - nơi hỗ trợ lập trình viên gỡ lỗi cho trang web. Phải nói là nó hết sức đơn giản. Dường như Safari tạo ra không dành cho gỡ lỗi. Mình mất một hồi loay hoay để tìm cách xem dữ liệu truyền lên qua API như thế nào, hay thậm chí một Object được in ra console.log còn không thể xem được đầy đủ thông tin!?

    Đấy, chỉ riêng khoản đó thôi cũng là lý do để mình quay trở lại với Chrome. Có thể Safari rất tập trung vào quyền riêng tư và bảo mật cho nên họ làm khó các yêu cầu này lên. Bù lại có lẽ nếu duyệt web thông thường, bạn sẽ rất thích Safari đấy!

    » Xem thêm

Vấn đề

README là một trong những tệp quan trọng nhất của bất kỳ dự án lập trình nào. Đó là một tệp văn bản thường được viết bằng Markdown giới thiệu về dự án và giải thích nội dung của dự án. Nó giúp mọi người hiểu cách cài đặt và sử dụng mã bạn đã viết, cũng như cách mọi người có thể phát triển dự án cùng với bạn.

Tại sao nên viết README?

Trở lại năm 2010, Tom Preston-Werner đã ủng hộ phát triển dự án theo hướng viết README của bạn trước, trước khi bạn làm bất cứ điều gì khác. Anh ấy nói rằng, mặc dù đã có các phương pháp lập trình và các cách vận hành dự án như TDD và SCRUM, nhưng sẽ tốt hơn nếu như những người khác hiểu được ngay dự án của bạn thông qua mô tả có ở trong README.

Viết README là điều cần thiết để có thể tạo ra một ứng dụng tốt. Nó sẽ định hình giúp bạn những việc cần làm sau này trong dự án.

Như Preston-Werner nói sẽ dễ dàng hơn nhiều để bắt tay vào viết README khi bắt đầu dự án của bạn, đó là thời điểm bạn có động lực nhất. Khi bạn kết thúc dự án của mình, viết README sẽ giống như một nhiệm vụ khác, một công việc nhỏ khác. Điều đó sẽ làm giảm sự hứng thú của bạn khi viết nó.

Nhưng bằng cách nào đi chăng nữa, bạn vẫn cần một tệp README truyền tải đầy đủ nội dung, bởi vì rất ít người sẽ rà soát mã của bạn để hiểu nó hoạt động như thế nào. Nó tốn thời gian và họ có thể không có chuyên môn kỹ thuật để hiểu nó.

Ngoài ra, không chỉ có các developer mới quan tâm đến README của bạn. Các nhà tuyển dụng cũng vậy, họ sẽ xem README tìm hiểu khả năng của bạn. README một lần nữa thể hiện sự chuyên nghiệp của bạn.

Ngay cả khi bạn đang làm dự án cá nhân thì README vẫn quan trọng. Hãy tưởng tượng sau một thời gian bạn quay lại để tiếp tục dự án. Với một README tốt bạn sẽ biết ngay dự án đó đang làm gì và giúp bạn có thể bắt tay vào làm ngay lập tức.

Viết README như thế nào?

Viết một tệp README cần có bố cục rõ ràng và mạch lạc, điều đó đôi khi còn phụ thuộc vào khả năng và tính thẩm mỹ của mỗi người.

Dưới đây là một số điều cần thiết khi bạn viết README của mình:

  • Title (Tiêu đề)
  • Introduction (Giới thiệu - nó nói về cái gì và tại sao bạn viết nó)
  • Install (Cài đặt thế nào?)
  • Use (Cách sử dụng)
  • Technologies Used (Công nghệ được sử dụng - thư viện, phiên bản...)
  • Acknowledgments (Sự nhìn nhận - là nơi bạn viết ra những lời cảm ơn, những bài viết hay bất kì điều gì ở một nơi khác truyền cảm hứng hoặc giúp bạn hoàn thành dự án này)

Đó là những điều cần thiết tối thiểu để giúp ích cho bạn và những người khác. Ngoài những mục trên bạn có thể thêm những mục mà bạn cảm thấy là cần thiết cho dự án. Ví dụ như:

  • Table of contents - ToC (Mục lục - hữu ích nếu README của bạn dài)
  • List of features - LoF (Danh sách các tính năng)
  • Examples (Ví dụ về việc sử dụng - Mã hoặc hình ảnh)

Ví dụ về README hữu ích

Dưới dây là một số dự án trên github mà có tệp README được trình bày rất tốt:

Ngoài ra, còn có một số công cụ giúp bạn trình bày được README một cách có hệ thống. Một trong số đó là readme.so. Đây là một công cụ hỗ trợ tạo một tệp README với đầy đủ các đầu mục, bạn có thể trải nghiệm trực tiếp trên trang web, hoặc tham khảo những đầu mục mà công cụ cung cấp để tự tạo tệp thủ công.

readme.so

README là một tệp cần thiết cho các dự án lập trình của bạn, ngay cả khi nó chỉ dành cho dự án của chính bạn. Bạn nghĩ sao về những điều ở bên trên hay có điều gì khác mà bạn nghĩ là cần thiết cho một README không? Hãy để lại bình luận nhé!

Bài viết được dịch ở x-team và được chỉnh sửa lại để phù hợp cho bạn đọc.

Cao cấp
Hello

Bí mật ngăn xếp của Blog

Là một lập trình viên, bạn có tò mò về bí mật công nghệ hay những khoản nợ kỹ thuật về trang blog này? Tất cả bí mật sẽ được bật mí ngay bài viết dưới đây. Còn chờ đợi gì nữa, hãy bấm vào ngay!

Là một lập trình viên, bạn có tò mò về bí mật công nghệ hay những khoản nợ kỹ thuật về trang blog này? Tất cả bí mật sẽ được bật mí ngay bài viết dưới đây. Còn chờ đợi gì nữa, hãy bấm vào ngay!

Xem tất cả

Đăng ký nhận thông báo bài viết mới

hoặc
* Bản tin tổng hợp được gửi mỗi 1-2 tuần, huỷ bất cứ lúc nào.

Bình luận (2)

Nội dung bình luận...
Avatar
Trịnh Cường2 năm trước

cảm ơn bạn, bài viết như lồng đèn sáng chói vậy

Trả lời
Avatar
Xuân Hoài Tống2 năm trước

Cảm ơn bạn Cường

Avatar
Đức Tống3 năm trước

Bài viết rất hữu ích ạ

Trả lời