Tệp README là gì và cách sử dụng chúng đúng cách

Nếu bạn làm việc với các dự án kỹ thuật số, sớm muộn gì bạn cũng sẽ bắt gặp một loại tệp có tên là [tên tệp]. READMEMặc dù thoạt nhìn có vẻ chỉ là một tài liệu văn bản đơn giản, nhưng nó quan trọng hơn nhiều so với vẻ bề ngoài: đó là... thư xin việc cho dự án của bạnĐây là điểm khởi đầu cho bất kỳ ai muốn biết bạn đã làm gì, cách sử dụng nó và liệu nó có đáng để họ bỏ thời gian ra hay không.

Trong thế giới phát triển phần mềm, khoa học dữ liệu, hoặc thậm chí trong công việc học thuật và các dự án hợp tác, một README được viết rất tốt Việc này giúp bạn tiết kiệm thời gian, tránh sai sót và giúp người khác (hoặc chính bạn sau vài tháng) dễ dàng hiểu được mục đích của dự án. Hãy cùng tìm hiểu kỹ hơn về file README, mục đích của chúng, những nội dung cần có và cách tận dụng tối đa chúng.

Vậy chính xác thì file README là gì?

Tệp README là một tài liệu văn bản đi kèm với một dự án kỹ thuật số Mục tiêu chính của nó là giải thích rõ ràng dự án chứa gì, dùng để làm gì và cách sử dụng như thế nào. Dịch theo nghĩa đen, nó giống như "hãy đọc tôi", và đó chính xác là chức năng của nó: là thứ đầu tiên mà người dùng đọc khi họ mở một kho lưu trữ, một thư mục dữ liệu hoặc một gói phần mềm.

Loại tệp này có thể được lưu ở nhiều định dạng khác nhau. định dạng văn bản: từ tác phẩm kinh điển readme.txt (văn bản thuần túy) lên đến readme.doc, readme.1st hoặc các phần mở rộng ít phổ biến hơn như . TôiĐịnh dạng cụ thể thường được điều chỉnh cho phù hợp với hệ điều hành và chương trình sẽ được dùng để hiển thị nó.để bất kỳ người dùng nào cũng có thể mở và đọc tệp mà không gặp bất kỳ khó khăn nào.

Ngày nay, đặc biệt trong các dự án phần mềm và kho mã nguồn, định dạng phổ biến nhất là README.mdPhần mở rộng .md cho biết tệp được ghi bằng ngôn ngữ lập trình nào. MarkdownHTML là một ngôn ngữ đánh dấu rất đơn giản cho phép bạn chuyển đổi văn bản thành HTML chỉ bằng một vài ký hiệu để định dạng. Điều này giúp việc định dạng nội dung trở nên dễ dàng hơn. dễ đọc cả ở dạng thô và dạng hiển thị trên web.Ngoài ra, nó còn cho phép sử dụng tiêu đề, danh sách, liên kết, bảng, hình ảnh và nhiều nội dung khác một cách dễ dàng.

Một tệp README được cấu trúc tốt sẽ cung cấp cho người dùng hoặc người đóng góp thông tin cần thiết. Bản tóm tắt đầy đủ và dễ hiểu về dự ánTài liệu này không nhằm mục đích cung cấp thông tin đầy đủ và toàn diện, mà là một hướng dẫn thực tiễn: dự án này làm gì, tại sao nó hữu ích, cách bắt đầu sử dụng và tìm thêm thông tin nếu cần.

Trong lĩnh vực dữ liệu, ví dụ như trong các kho lưu trữ tập dữ liệu, việc có tệp README (đôi khi ở định dạng) là rất phổ biến. readme.txt) sưu tầm Thông tin chung, tác giả, từ khóa, phạm vi địa lý và thời gian, giấy phép sử dụng và phương pháp luận được sử dụng để tạo ra hoặc thu thập dữ liệu, cũng như Phần mềm được đề xuất để làm việc với chúng.

Lịch sử ngắn gọn và cách sử dụng tiêu chuẩn của các tệp README.

Mặc dù ngày nay chúng ta chủ yếu liên tưởng đến các nền tảng như GitHub, nhưng việc đưa tệp README vào các gói phần mềm bắt nguồn từ... nhiều thập kỷ trướcCó những ví dụ được ghi chép lại từ thời xa xưa. giữa những năm 70Vào thời điểm đó, các chương trình đã được phân phối kèm theo một tài liệu nhỏ giải thích nội dung và cách sử dụng.

Theo thời gian, tập tục này trở nên phổ biến đến mức trong Tiêu chuẩn mã hóa GNU (Theo tiêu chuẩn mã hóa GNU) tệp README được coi là một yêu cầuNhững tiêu chuẩn này đã ảnh hưởng rất lớn đến hệ sinh thái phần mềm tự do và góp phần khiến cho tệp README trở nên gần như bắt buộc đối với bất kỳ gói phần mềm nghiêm túc nào.

Khi internet trở nên phổ biến nền tảng tiêu chuẩn để phân phối phần mềmNhiều dự án bắt đầu chuyển một số thông tin trước đây nằm trong tệp README (hướng dẫn sử dụng, giấy phép, tin tức, v.v.) sang các trang web, wiki hoặc các nền tảng khác. gói mã nguồn dạng nén tarballTuy vậy, tệp README không bao giờ biến mất: trong nhiều trường hợp, nó vẫn còn nguyên vẹn. tóm tắt địa phươngMặc dù đôi khi nó vẫn còn thiếu sót một số chi tiết so với tài liệu trực tuyến.

Sự phổ biến của các nền tảng như GitHub Và những nỗ lực của các cộng đồng phần mềm tự do lâu đời hơn đã đưa các tệp README trở lại vị trí hàng đầu. Ví dụ, trên GitHub, nếu một kho lưu trữ chứa tệp README trong thư mục gốc, hệ thống sẽ tự động thêm nó. Nó tự động chuyển đổi sang HTML và hiển thị trên trang chủ. Đây là điểm nhấn của dự án, nên đó là điều đầu tiên bạn nhìn thấy khi bước vào.

Hơn nữa, khái niệm "tệp readme" đôi khi được sử dụng trong một chung Để chỉ bất kỳ tài liệu ngắn nào giải thích nội dung của một thư mục hoặc dự án, ngay cả khi tệp đó không được đặt tên chính xác là README. Nhiều dự án phần mềm mã nguồn mở phân phối một bộ tệp tiêu chuẩn cùng với tệp README, mỗi tệp đều có một chức năng được xác định rõ ràng.

Các tệp điển hình đi kèm với tệp README

Trong các dự án tuân theo các tiêu chuẩn như Tiêu chuẩn Gnits hoặc những dữ liệu được tạo ra bằng các công cụ như Công cụ tự động GNUNgoài tệp README chính, người ta thường tìm thấy các tệp văn bản khác bổ sung thông tin dự án. Một số tệp điển hình nhất là:

• READMEThông tin chung về dự án, mục đích và tầm nhìn tổng thể.
• TÁC GIẢ: Danh sách các tác giả chính hoặc cộng tác viên.
• THANKSLời cảm ơn dành cho những cá nhân hoặc tổ chức đã giúp đỡ.
• THAY ĐỔI: Nhật ký thay đổi chi tiết, được thiết kế chủ yếu dành cho các nhà phát triển.
• NEWS: Nhật ký thay đổi ngắn gọn và dễ hiểu hơn dành cho người dùng cuối.
• INSTALLHướng dẫn lắp đặt cụ thể và các yêu cầu kỹ thuật.
• SAO CHÉP / CẤP PHÉPVăn bản giấy phép phần mềm về sử dụng và phân phối.
• GIỎICác lỗi thường gặp và cách báo cáo lỗi chính xác.
• FAQCác câu hỏi thường gặp và câu trả lời.
• ALLDanh sách các nhiệm vụ đang chờ xử lý và các cải tiến dự kiến ​​trong tương lai.

Tất cả các tài liệu này, cùng với tệp README, tạo thành... khung sườn của tài liệu cơ bản của nhiều gói. Trong một số trường hợp, một số thông tin này được sao chép cả trong kho lưu trữ và trên trang web dự án để tạo điều kiện thuận lợi cho việc truy cập từ các kênh khác nhau.

Vai trò của tệp README trên GitHub và các nền tảng tương tự.

Trên GitHub, tệp README đóng một vai trò đặc biệt quan trọng. Trước hết, nó thường... điều đầu tiên mà bất cứ ai nhìn thấy những chuyến thăm đó kho lưu trữ của bạnNếu tài liệu được thực hiện tốt, chỉ trong vài giây, người ta sẽ hiểu rõ dự án này làm gì, tại sao nó có thể gây hứng thú, cách thiết lập và vận hành, cũng như ai là người đứng sau dự án.

GitHub tự động nhận diện tệp README khi nó được đặt ở một số vị trí nhất định trong kho lưu trữ. Nếu bạn đặt nó trong thư mục .github, trong thư mục gốc hoặc trong thư mục docsNền tảng phát hiện ra điều đó và hiển thị nổi bật cho khách truy cập. Khi có nhiều tệp README, GitHub sẽ tuân theo một quy tắc nhất định. thứ tự ưu tiên: tìm kiếm đầu tiên trong .github, sau đó ở gốc và cuối cùng là ở docs.

Ngoài ra, nếu bạn tạo một kho lưu trữ công khai có tên trùng khớp chính xác với tên của bạn, tên người dùng Và nếu bạn thêm một tệp README vào thư mục gốc, tệp đó sẽ tự động trở thành tệp README của bạn. Tệp tin READMENó được hiển thị trên trang người dùng của bạn, cho phép bạn tạo một phần trình bày tùy chỉnh bằng cách sử dụng GitHub Flavored Markdown.

Khi một tệp README (hoặc bất kỳ tệp .md nào) được xem trên GitHub, nền tảng này sẽ tự động tạo ra một tệp README. Mục lục Dựa trên tiêu đề tài liệu. Bạn có thể xem mục lục này bằng cách nhấp vào biểu tượng "Outline", điều này giúp việc điều hướng các tệp README dài có nhiều phần trở nên dễ dàng hơn nhiều.

GitHub cũng cho phép liên kết trực tiếp đến các phần cụ thểMỗi tiêu đề tự động tạo một liên kết; chỉ cần di chuột qua tiêu đề sẽ hiển thị biểu tượng liên kết. Điều này cho phép bạn chia sẻ các URL trỏ trực tiếp đến phần cụ thể trong tệp README mà bạn muốn làm nổi bật (ví dụ: phần cài đặt hoặc phần đóng góp).

Có một chi tiết thực tế quan trọng: vì lý do hiệu năng, nếu tệp README của bạn vượt quá... 500 KB về kích thước, GitHub sẽ cắt bớt nội dung Từ điểm đó trở đi trong giao diện hiển thị. Do đó, nên dành tệp README cho những thông tin cần thiết và chuyển các hướng dẫn hoặc tài liệu dài sang wiki hoặc tài liệu riêng biệt.

Định dạng và liên kết trong tệp README

Để giúp việc bảo trì tệp README dễ dàng hơn và hoạt động tốt cả trên GitHub lẫn các bản sao cục bộ, bạn nên sử dụng phương pháp sau: liên kết tương đối và đường dẫn hình ảnh tương đối so với tệp chứa chúng. Ví dụ, nếu bạn có tệp README trong thư mục gốc và một tài liệu... docs/CONTRIBUTING.mdĐường dẫn trong tệp README sẽ trông giống như thế này: (docs/CONTRIBUTING.md).

Loại liên kết tương đối này có nghĩa là khi chuyển đổi nhánh hoặc sao chép kho lưu trữ, Các tuyến đường vẫn hoạt động bình thường. mà không cần phải sửa đổi chúng. GitHub tự động chuyển đổi các đường dẫn này để trỏ đến phiên bản tệp chính xác dựa trên nhánh được hiển thị. Các đường dẫn bắt đầu bằng /được hiểu tương đối so với thư mục gốc của kho lưu trữ, cũng như các toán tử thông dụng như... ./ o ../.

Điều quan trọng là văn bản liên kết Hãy giữ liên kết trên một dòng duy nhất, vì việc chia nó thành nhiều dòng có thể gây ra lỗi. Ngoài ra, hãy tránh sử dụng các liên kết tuyệt đối đến các tệp trong kho lưu trữ nội bộ, vì chúng có thể bị hỏng nếu URL cơ sở thay đổi hoặc có một nhánh được tạo ra.

Về phạm vi của tài liệu, cần nhớ rằng tệp README chỉ nên chứa những thông tin sau: Thông tin cần thiết để bắt đầu sử dụng và đóng góp cho dự án. Đối với tài liệu mở rộng (sách hướng dẫn sử dụng, hướng dẫn API đầy đủ, v.v.), sẽ gọn gàng hơn nếu sử dụng một cái gì đó tương tự. wiki hoặc một hệ thống tài liệu riêng biệt, liên kết nó từ chính tệp README.

Mục đích thực sự của tệp README là gì?

Trên thực tế, ngoài lý thuyết, tệp README còn có chức năng như sau: hướng dẫn ban đầu và điểm tham chiếuMục đích của tài liệu này không phải là thay thế các tài liệu chính thức chi tiết, mà là cung cấp một lời giải thích có hệ thống và thiết thực về những khía cạnh quan trọng nhất của dự án.

Một trong những công dụng phổ biến nhất của nó là: giải thích mục tiêu Trong phần mô tả dự án, hãy nêu rõ dữ liệu hoặc tệp tin mà dự án bao gồm, hướng dẫn cách bắt đầu sử dụng và chỉ rõ các yêu cầu kỹ thuật chính. tránh các lỗi do sử dụng không đúng cách gây ra.Khi nhiều người dùng cùng làm việc trên cùng một đoạn mã hoặc dữ liệu, một tệp README rõ ràng sẽ giúp tránh được vô số câu hỏi lặp đi lặp lại.

Trong các dự án chung, đặc biệt là trong các nhóm lớn hoặc cộng đồng mã nguồn mở, tệp README gần như là một phần không thể thiếu. thành phần cơ sở hạ tầng truyền thôngNó giúp thống nhất kỳ vọng, thể hiện mức độ hoàn thiện của dự án, xác định cách thức đóng góp và làm rõ những hỗ trợ được cung cấp (nếu có).

Ngay cả trong các dự án cá nhân, ngay cả khi chỉ có bạn thực hiện, một tệp README được viết tốt vẫn đóng vai trò như một công cụ hỗ trợ đắc lực. trí nhớ dài hạnTheo thời gian, rất dễ quên các quyết định, các mối phụ thuộc hoặc các bước cài đặt; việc ghi chép lại sẽ giúp bạn tránh phải "tìm lại" dự án của mình sau nhiều tháng.

Do đó, README không chỉ là một hình thức: nó là một công cụ thiết thực giúp cải thiện tổ chức, giao tiếp và khả năng bảo trì thuộc bất kỳ loại dự án kỹ thuật số nào.

Khi nào thì nên tạo file README?

Câu trả lời ngắn gọn là nên tạo một file README. bất cứ khi nào có một dự án sẽ được sử dụng, xem xét hoặc bảo trì. Bởi một người nào đó không phải là người tạo ra ban đầu… và điều đó bao gồm cả chính bạn trong tương lai. Nó không nhất thiết phải là một kho lưu trữ mã nguồn mở khổng lồ: nó chỉ cần có một chút phức tạp hoặc nội dung gây ra nhiều câu hỏi.

Một số ví dụ cho thấy tệp README đặc biệt hữu ích là: các dự án web hoặc lập trìnhTrong đó, việc giải thích các yêu cầu, quy trình phát triển, lệnh khởi động và môi trường chạy là điều nên làm. Điều này cũng rất thú vị ở... các thư mục chứa dữ liệu quan trọngĐể làm rõ dữ liệu đó thể hiện điều gì, nguồn gốc và những hạn chế có thể có của nó.

Các bối cảnh điển hình khác là các trang web được lưu trữ trên máy chủthường bao gồm một tệp README với hướng dẫn triển khai, hoặc công việc học thuật và kỹ thuậtTrong đó, tệp README có thể mô tả các kịch bản, thí nghiệm, phiên bản công cụ được sử dụng hoặc cách tái tạo kết quả.

En dự án hợp tácDù là nội bộ hay công khai, tệp README gần như là bắt buộc. Nó giúp người mới tham gia dự án dễ dàng hơn và đóng vai trò là tài liệu tham khảo chung để duy trì các tiêu chuẩn sử dụng và đóng góp nhất quán giữa tất cả các bên liên quan.

Một tệp README tốt nên chứa những thông tin gì?

Một README hiệu quả không cần phải dài, nhưng nó cần phải... được sắp xếp tốt và rất rõ ràngCó một số thông tin cơ bản hầu như luôn cần phải có, và một số nội dung tùy chọn khác sẽ bổ sung thêm nhiều giá trị tùy thuộc vào loại dự án.

Tối thiểu, hầu hết các kho lưu trữ và gói phần mềm được ghi chép đầy đủ đều bao gồm... tên dự án, One Mô tả ngắn gọn về mục tiêu, bản tóm tắt nội dung của kho lưu trữ, Hướng dẫn sử dụng hoặc cài đặt và các yêu cầu thiết yếu (các phụ thuộc, phiên bản ngôn ngữ tối thiểu, hệ điều hành, v.v.).

Ngoài ra, rất nên bổ sung thêm một số phương thức liên hệ hoặc hỗ trợNgay cả khi đó chỉ là một email hoặc một liên kết đến mục "Sự cố" của kho lưu trữ, điều này sẽ hướng dẫn bất kỳ ai gặp vấn đề về nơi và cách báo cáo chúng, thay vì để họ bối rối và không chắc chắn nên liên hệ với ai.

Ngoài những thông tin cơ bản, việc bổ sung thêm thông tin về... ngày tạo hoặc phiên bản hiện tại, danh sách các tác giả hoặc các bên chịu trách nhiệm, giấy phép sử dụng và bất kỳ thông báo liên quan nào về việc sử dụng dữ liệu hoặc mã (ví dụ: nếu đó là phiên bản thử nghiệm hoặc không phù hợp để sử dụng trong môi trường sản xuất).

Thứ tự sắp xếp cũng ảnh hưởng đến khả năng đọc hiểu: thông tin quan trọng nhất (dự án là gì, mục đích của dự án là gì, cách sử dụng) nên được trình bày trước. ở đầu tài liệuĐể lại các chi tiết phụ, thông tin bổ sung hoặc ghi chú lịch sử cho phần sau. Bằng cách này, người chỉ xem lướt qua cũng có thể nắm được ý chính chỉ với một cái nhìn nhanh.

Nội dung điển hình của một tệp README trong phần mềm

Trong các dự án phần mềm, các tệp README thường được mở rộng thêm bằng cách bao gồm một số khối chủ đề bổ sung. Trong nhiều trường hợp, tệp này tóm tắt ngắn gọn... hướng dẫn thiết lậphướng dẫn cài đặt, hướng dẫn sử dụng cơ bản, một tập tin kê khai (Giải thích công dụng của từng thư mục quan trọng) và tóm tắt giấy phép.

Việc bao gồm một phần với cũng khá phổ biến. thông tin về nhà phát triển hoặc nhómCác cách thức có thể đóng góp cho dự án, danh sách các lỗi đã biết và hướng dẫn khắc phục sự cố ngắn gọn cho các vấn đề thường gặp. Tất cả những điều này giúp bất kỳ ai truy cập kho lưu trữ đều có được thông tin cần thiết. một tầm nhìn toàn cầu và thực tiễn mà không cần phải tìm kiếm ở nơi khác.

Trong một số trường hợp, tệp README có thể chứa một phần nhỏ. Thay đổi nhật ký Hoặc trỏ đến một tệp CHANGELOG bên ngoài. Việc thêm mục "Tin tức" hoặc "Có gì mới" để làm nổi bật những thay đổi quan trọng giữa các phiên bản cũng khá phổ biến, đặc biệt khi đối tượng mục tiêu là người dùng cuối chứ không phải nhà phát triển.

Trong bối cảnh các kho lưu trữ học thuật hoặc dữ liệu, ngoài phần mô tả nội dung, nhiều mẫu khuyến nghị nên mô tả thêm như sau: phương pháp thu thập hoặc tạo ra dữ liệuCác biến số được bao gồm, phạm vi thời gian và địa lý của thông tin, và bất kỳ hạn chế nào liên quan đến việc sử dụng hoặc diễn giải.

Tệp README như một công cụ giao tiếp trên GitHub

Khi bạn tải một dự án lên GitHub, tệp README không chỉ trở thành tài liệu hướng dẫn mà còn là một công cụ hữu ích. yếu tố giao tiếp và thuyết trìnhTrên thực tế, chính nền tảng này cũng khuyến nghị nên thêm tệp README vào bất kỳ kho lưu trữ công khai nào để giúp người truy cập nhanh chóng hiểu được dự án đó nói về cái gì.

Bạn có thể sử dụng tệp README để giải thích. Dự án này làm gì?Tại sao nó có thể hữu ích, cách bắt đầu (ví dụ: với phần "Bắt đầu"), nơi để tìm trợ giúp (vấn đề, diễn đàn, trò chuyện, v.v.) và ai là người tích cực duy trì mã nguồn. Tất cả những điều này ảnh hưởng đến chất lượng cảm nhận và sự tin tưởng mà kho lưu trữ tạo ra.

Trong nhiều trường hợp, các nhà phát triển sử dụng kho lưu trữ GitHub của họ như... danh mục đầu tư chuyên nghiệpTrong bối cảnh này, các tệp README được soạn thảo tốt tạo ra sự khác biệt rất lớn: chúng cho phép nhà tuyển dụng hoặc các bên quan tâm khác xem nhanh phạm vi của dự án, các công nghệ được sử dụng và phương pháp làm việc của tác giả.

Nếu mục đích của bạn không phải là thu hút đóng góp hoặc quảng bá kho lưu trữ (ví dụ: nếu đó là một dự án riêng tư hoặc nội bộ), thì một tệp README quá chi tiết không phải là bắt buộc. Tuy nhiên, việc duy trì ít nhất một tệp README thường là điều thiết thực. tài liệu cơ bản tối thiểu Dùng cho mục đích cá nhân và nhóm.

GitHub cũng cung cấp một số tiện ích cụ thể liên quan đến README: nó tự động tạo chỉ mục, hỗ trợ huy hiệu và biểu tượng, và cho phép bạn chèn hình ảnh, GIF hoặc video để giới thiệu dự án. Nếu sử dụng hiệu quả, tất cả các yếu tố này có thể làm cho README trở nên hiệu quả hơn. hấp dẫn hơn và dễ điều hướng hơn.

Cách cấu trúc và cải thiện tệp README của bạn

Khi phân tích các kho lưu trữ phổ biến (ví dụ: các dự án từ các tổ chức công nghệ lớn hoặc các cơ quan vũ trụ), người ta nhận thấy rằng các tệp README của chúng thường có một số điểm chung. mẫu phổ biếnMặc dù mỗi dự án đều duy trì bản sắc hình ảnh và nội dung riêng.

Thường thấy tiêu đề rõ ràng và hình ảnh bìa khả thi (chẳng hạn như logo hoặc biểu ngữ cho dự án), tiếp theo là một số huy hiệu tóm tắt trạng thái dự án, giấy phép, phiên bản hiện tại hoặc trạng thái thử nghiệm. Sau đó thường có một mô tả dự án, một phần về trạng thái (ổn định, đang phát triển, thử nghiệm, v.v.) và một phần trình bày các ví dụ hoặc ảnh chụp màn hình.

Cũng rất thường thấy một khối có quyền truy cập vào dự án (các liên kết đến phiên bản đã triển khai, tài liệu và các gói đã xuất bản), danh sách các công nghệ được sử dụng, các phần dành riêng cho người đóng góp, nhà phát triển và, tất nhiên, giấy phépNhững yếu tố này giúp tệp README vừa đóng vai trò là hướng dẫn nhanh cho người dùng, vừa là danh thiếp cho những người đóng góp tiềm năng.

Về thiết kế, mặc dù đây là một tập tin văn bản, nhưng vẫn có nhiều cách để làm cho nó dễ đọc hơn: sử dụng các tiêu đề được cấu trúc tốt, danh sách có thứ tự và không có thứ tự, bảng biểu khi thích hợp, và In đậm chữ để làm nổi bật những ý chính.Trong Markdown, bạn cũng có thể chèn hình ảnh, GIF và các yếu tố trang trí nhỏ (như biểu tượng cảm xúc) để làm cho văn bản thân thiện hơn với người dùng, nhưng luôn phải đảm bảo tính rõ ràng.

Một mẹo ít được nhắc đến là luôn viết với suy nghĩ về một người nào đó... Anh ta hoàn toàn không biết gì về dự án này.Điều này có nghĩa là tránh giả định về kiến ​​thức nền tảng, sử dụng ngôn ngữ rõ ràng và trực tiếp, và làm rõ các thuật ngữ kỹ thuật ngay khi chúng xuất hiện. Và tất nhiên, luôn cập nhật tệp README bất cứ khi nào có thay đổi liên quan trong dự án.

Giấy phép, đóng góp và quyền tác giả

Trong các dự án mã nguồn mở, một phần đặc biệt quan trọng của tệp README là phần dành cho... giấy phépViệc công bố mã nguồn trong kho lưu trữ công cộng không tự động biến nó thành phần mềm tự do; cần phải nêu rõ các điều kiện để nó được coi là phần mềm tự do. để được sử dụng, sửa đổi và phân phối lại.

Cách làm phổ biến nhất là sử dụng các giấy phép nổi tiếng (MIT, Apache, GPL, Creative Commons cho tài liệu, v.v.) và liên kết từ tệp README đến tệp LICENSE hoặc COPYING của kho lưu trữ. Bằng cách này, bất kỳ ai quan tâm đều biết ngay họ có thể làm gì với mã nguồn và nghĩa vụ của họ là gì (ví dụ: ghi công, chia sẻ tương tự, giới hạn trách nhiệm, v.v.).

Một phần quan trọng khác trong một tệp README hoàn chỉnh là... hướng dẫn đóng gópPhần này giải thích cách người khác có thể đóng góp cho dự án: hướng dẫn về phong cách, quy trình gửi yêu cầu kéo (pull request), cách báo cáo lỗi, các loại đóng góp được chấp nhận và nơi điều phối công việc. Đôi khi thông tin này được chứa trong một tệp CONTRIBUTING.md riêng biệt được liên kết từ tệp README.

Việc làm cho mọi thứ trở nên dễ thấy cũng là một việc làm tốt. các cá nhân và nhà phát triển đóng gópMột số dự án bao gồm các bảng với hình đại diện và tên được liên kết với hồ sơ của họ, trong khi những dự án khác chỉ đơn giản liệt kê những người dùng chính. Hành động này không chỉ ghi nhận công việc mà còn tạo điều kiện thuận lợi cho việc liên lạc trực tiếp nếu ai đó cần nói chuyện với một thành viên cụ thể trong nhóm.

Cuối cùng, cần dành vài dòng để giải thích. cách nhận trợ giúp Và những kênh nào hiện có: các vấn đề trên GitHub, diễn đàn, danh sách gửi thư, trò chuyện trực tuyến, v.v. Nếu dự án không cung cấp hỗ trợ chính thức, việc nêu rõ điều này cũng rất cần thiết để tránh hiểu lầm.

Với tất cả những điều trên, tệp README trở thành một phần cốt lõi của bất kỳ dự án kỹ thuật số nào: Nó giải thích nó là gì, hoạt động như thế nào, ai bảo trì nó và trong điều kiện nào thì nó có thể được sử dụng.Việc chăm sóc nội dung và cập nhật thường xuyên là một khoản đầu tư nhỏ nhưng tạo ra sự khác biệt lớn trong cách người khác nhìn nhận và sử dụng tác phẩm của bạn.