Cách viết Readme cho một dự án

README là gì?

• Là 1 tệp văn bản (.txt và .md) hoạt động như document của dự án để giới thiệu dự án cho người dùng hoặc nhà phát triển khác.
  
  
• Nó thường là phần documentation và landing page dễ thấy nhất cho hầu hết các dự án nguồn mở.
  
  
• Ngay cả tên tệp README cũng được viết hoa toàn bộ để thu hút sự chú ý của người đọc và đảm bảo đó là điều đầu tiên họ đọc.

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

• Trở lại năm 2012, 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 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ó.
  
  
• 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.

Một số điều cần thiết khi viết README

Một tệp README cần có bố cục rõ ràng, mạch lạc và đặc biệt là đơn giản dễ hiểu, nên sử dụng tiếng anh đơn giản thay vì thuật ngữ. Điều này phụ thuộc vào khả năng và tính thẩm mỹ của mỗi người.

• Title: tiêu đề của dự án
  
  
• Introduction: Viết một đoạn văn ngắn mô tả dự án
  
  
• Install:
  • Hướng dẫn install dự án trên máy:
    1. Sao chép dự án từ kho lưu trữ: git clone [đường dẫn khi lưu tữ]
    2. Di chuyển vào thư mục dự án: cd [tên thư mục]
    3. Cài đặt các dependencies: npm install
       
       
• Use:
  • Hướng dẫn cách sử dụng dự án, bao gồm một số câu lệnh cơ bản, ví dụ:
    1. Chạy dự án trong môi trường phát triển: npm run dev
    2. Tạo bản build sản phẩm: npm run build
    3. Kiểm tra và sửa lỗi: npm run lint
  • Hướng dẫn follow với git
    1. Tạo tên nhánh đúng format
    2. Khi nào thì sẽ tạo PR vào branch Dev và khi nào sẽ tạo PR và master
    3. Create name PR đúng format
       
       
• Technologies Used: Công nghệ được sử dụng – thư viện, phiên bản…
  
  
• Directory structure: Mô tả ngắn gọn về cấu trúc của dự án
  
  
• Contribute: Hướng dẫn cho người dùng khác về cách đóng góp vào dự án. Đây có thể là các quy tắc pull request, đại loại về GIT, hướng dẫn về phân công công việc hoặc yêu cầu báo cáo lỗi.
  
  
• 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à
  
  

Một số dự án trên github có tệp README được trình bày rất tốt

• ai/size-limit: Hình ảnh đầy đủ và giải thích chi tiết.
• crelies/AdvancedList: Giải thích ngắn gọn và sử dụng Emojis bắt mắt.
• release-it/release-it: Có GIF, hướng dẫn đầy đủ.
• ArmynC/ArminC-AutoExec: Gọn gàng, mô tả rõ ràng.

Tổng kết

Trên đây là một số kiến thức mình đã tìm hiểu và chọn lọc, hi vọng sẽ giúp ích được cho mọi người.