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 tệp có tên là README . Mặc dù thoạt nhìn 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à phần giới thiệu dự án của bạn , điểm tiếp cận đầu tiên 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, hay thậm chí trong công việc học thuật và các dự án hợp tác, một tệp README được viết tốt sẽ loại bỏ sự nhầm lẫn, ngăn ngừa lỗi và giúp người khác (hoặc thậm chí chính bạn sau vài tháng) dễ dàng hiểu nhanh mục đích của dự án. Hãy cùng tìm hiểu kỹ hơn về tệp README là gì, chúng được sử dụng để làm gì, chúng nên bao gồm những gì và làm thế nào để 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 đích chính là giải thích rõ ràng dự án đó chứa những gì, dùng để làm gì và cách sử dụng như thế nào. Dịch theo nghĩa đen, nó có thể được hiểu là "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 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 văn bản khác nhau : từ định dạng cổ điển readme.txt (văn bản thuần túy) đến readme.doc , readme.1st , hoặc các phần mở rộng ít phổ biến hơn như .me . Đị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 sử dụng để xem tệp, sao cho bất kỳ người dùng nào cũng có thể mở và đọc tệp mà không gặp khó khăn.

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.md . Phần mở rộng .md cho biết tệp được viết bằng Markdown , 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 nội dung dễ đọc cả ở dạng thô và khi được hiển thị trên trang web , đồng thời cho phép chèn tiêu đề, danh sách, liên kết, bảng, hình ảnh, v.v. mà không gặp khó khăn.

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 một bản tóm tắt đầy đủ và dễ hiểu về dự án . Nó không nhằm mục đích trở thành tài liệu toàn diện, mà là một hướng dẫn thực tế: dự án 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, rất phổ biến việc tệp README (đôi khi ở định dạng readme.txt ) bao gồ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 được sử dụng để tạo 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 đã có từ nhiều thập kỷ trước . Có những ví dụ được ghi nhận từ giữa những năm 70 , khi các chương trình đã được phân phối kèm theo một tài liệu ngắn giải thích nội dung và cách sử dụng của chúng.

Theo thời gian, thông lệ này trở nên phổ biến đến mức Tiêu chuẩn Mã hóa GNU hiện coi tệp README là một yêu cầu bắt buộc. Nhữ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 làm cho tệp README 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 web trở thành nền tảng tiêu chuẩn để phân phối phần mềm , nhiều dự án bắt đầu chuyển một số thông tin trước đây được chứa 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 tệp mã nguồn nén . Tuy nhiên, tệp README không bao giờ biến mất: trong nhiều trường hợp, nó vẫn tồn tại như một bản tóm tắt cục bộ , mặc dù đôi khi nó có phần không đầy đủ 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à các cộng đồng phần mềm mã nguồn mở lâu đời đã đư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 chuyển đổi nó thành HTML và hiển thị trên trang chủ của dự án , vì vậy đó là điều đầu tiên bạn thấy khi truy cập.

Hơn nữa, thuật ngữ "tệp readme" đôi khi được sử dụng một cách chung 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 cụ thể là README. Nhiều dự án phần mềm tự do 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 các dự án được tạo bằng các công cụ như GNU Autotools , ngoài tệp README chính, người ta thường 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 xương sống của tài liệu cơ bản cho nhiều gói phần mềm. 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à 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 vai trò đặc biệt quan trọng. Trước hết, nó thường là thứ đầu tiên mà bất kỳ ai nhìn thấy khi truy cập vào kho lưu trữ của bạn . Nếu tệp được viết tốt, chỉ trong vài giây, người dùng sẽ hiểu rõ dự án làm gì, tại sao nó có thể hữu ích, cách bắt đầu và 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 người dùng của bạn và thêm tệp README vào thư mục gốc, tệp đó sẽ tự động trở thành tệp README hồ sơ của bạn . Nó sẽ được hiển thị trên trang người dùng của bạn, cho phép bạn tạo phần giới thiệu tùy chỉnh bằng cách sử dụng định dạng Markdown của GitHub.

Khi xem một tệp README (hoặc bất kỳ tệp .md nào) trên GitHub, nền tảng này sẽ tự động tạo mục lục dựa trên các tiêu đề của 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 bạn 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. Bằng cách này, bạn có thể chia sẻ các URL trỏ trực tiếp đến phần 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 suất, nếu tệp README của bạn vượt quá 500 KiB , GitHub sẽ cắt bớt nội dung sau điểm đó trong chế độ xem được hiển thị. Do đó, bạn 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 phải nằm trên một dòng duy nhất, vì việc chia nó thành nhiều dòng có thể khiến liên kết hoạt động không đúng cách. Ngoài ra, bạn nên tránh sử dụng các liên kết tuyệt đối đến các tệp nội bộ trong kho lưu trữ, vì chúng có thể bị lỗi nếu URL cơ sở thay đổi hoặc kho lưu trữ được phân nhánh.

Về phạm vi của tài liệu, điều quan trọng cần nhớ là README chỉ nên chứa những thông tin thiết yếu 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 (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 wiki hoặc hệ thống tài liệu riêng biệt, liên kết đến đó từ chính README.

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

Trên lý thuyết, tập tin README đóng vai trò như một hướng dẫn ban đầu và điểm tham chiếu trong thực tế . Nó không nhằm mục đích thay thế tài liệu chính thức đầy đủ, mà chỉ cung cấp lời giải thích rõ ràng và thiết thực về các 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 README là: giải thích mục tiêu của dự án, mô tả dữ liệu hoặc tệp tin mà dự án bao gồm, hướng dẫn cách bắt đầu, nêu rõ các yêu cầu kỹ thuật chính và ngăn ngừa lỗi do sử dụng không đúng cách . Khi nhiều người dùng cùng làm việc trên cùng một mã hoặc dữ liệu, một README rõ ràng sẽ giúp tránh vô số câu hỏi lặp đi lặp lại.

Trong các dự án hợp tác, đặ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 thiết yếu của cơ sở hạ tầng giao tiếp . Nó giúp thống nhất kỳ vọng, chỉ ra mức độ trưởng thành 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 bạn là người duy nhất thực hiện chúng, một tệp README được viết tốt sẽ đóng vai trò như một bộ nhớ dài hạn . Theo thời gian, rất dễ quên các quyết định, các phụ thuộc hoặc các bước cài đặt; việc ghi lại chúng sẽ giúp bạn không 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 thủ tục hình thức: nó là một công cụ thiết thực giúp cải thiện việc tổ chức, giao tiếp và khả năng bảo trì của 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 tệp 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 người khác ngoài người tạo ra nó—và điều đó bao gồm cả chính bạn trong tương lai. Nó không cần phải là một kho lưu trữ mã nguồn mở khổng lồ; chỉ cần nó có một chút phức tạp hoặc nội dung gây ra thắc mắc.

Một số ví dụ về trường hợp tệp README đặc biệt hữu ích là các dự án web hoặc lập trình , nơi nó giúp 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. Nó cũng rất hữu ích trong các thư mục chứa dữ liệu quan trọng , để làm rõ dữ liệu đó đại diện cho điều gì, nguồn gốc của nó và bất kỳ hạn chế tiềm tàng nào.

Các ngữ cảnh điển hình khác là các trang web được lưu trữ trên dịch vụ lưu trữ , thường bao gồm tệp README với hướng dẫn triển khai, hoặc các công trình học thuật và kỹ thuật , trong đó 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ả.

Trong các dự án hợp tác , dù 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 để đảm bảo tính nhất quán trong việc sử dụng và đóng góp 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 cần phải được tổ chức tốt và rất rõ ràng . Có một số thông tin cơ bản hầu như luôn phải có, và các nội dung tùy chọn khác bổ sung giá trị đáng kể 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 , mô tả ngắn gọn về mục tiêu , 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 thêm một hình thức liên hệ hoặc hỗ trợ nào đó , ngay cả khi chỉ là địa chỉ email hoặc 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 đề biết nên báo cáo ở đâu và như thế nào, thay vì để họ bối rối và không biết liên hệ với ai.

Ngoài những thông tin cơ bản, thường thì nên 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 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ã nguồn (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 nó, cách sử dụng) nên được đặt ở đầu tài liệu , để lại các chi tiết phụ, phần ghi công mở rộng hoặc ghi chú lịch sử ở phần sau. Bằng cách này, người chỉ lướt qua cũng có thể nắm được ý chính ngay lập tức.

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, tệp README thường được mở rộng thêm bằng cách bao gồm một số phần chủ đề bổ sung. Trong nhiều trường hợp, tệp này chứa ngắn gọn hướng dẫn cấu hình , hướng dẫn cài đặt, hướng dẫn sử dụng cơ bản, danh sách tệp (giải thích mục đích của từng thư mục quan trọng) và tóm tắt giấy phép.

Thông thường, người ta cũng sẽ thêm một phần thông tin về nhà phát triển hoặc nhóm , cách thức đó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 người truy cập kho lưu trữ có được cái nhìn tổng quan toàn diện và thiết thực 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 nhật ký thay đổi ngắn gọn hoặc trỏ đến tệp nhật ký thay đổi bên ngoài. Việc bao gồ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 việc mô tả nội dung, nhiều mẫu khuyến nghị nên mô tả phương pháp thu thập hoặc tạo ra dữ liệu , cá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 mà còn là công cụ giao tiếp và trình bày . Trên thực tế, chính nền tảng này cũng khuyến khích thêm tệp README vào bất kỳ kho lưu trữ công khai nào để giúp khách truy cập nhanh chóng hiểu được dự án đó nói về điều gì.

Bạn có thể sử dụng tệp README để giải thích dự án 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 đang 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ư một hồ sơ chuyên nghiệp . Trong 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 chi tiết không phải là bắt buộc. Tuy nhiên, việc duy trì ít nhất một số tài liệu cơ bản để bạn và nhóm của bạn sử dụng thường là điều hữu ích.

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. Khi được sử dụng hiệu quả, tất cả các yếu tố này có thể làm cho README 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ố mẫu chung , mặc dù mỗi dự án vẫn duy trì bản sắc hình ảnh và nội dung riêng.

Thông thường, bạn sẽ thấy một tiêu đề rõ ràng và hình ảnh bìa (như logo hoặc banner của dự án), tiếp theo là một số huy hiệu hoặc biểu tượng 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ó phần mô tả dự án , phần về trạng thái (ổn định, đang phát triển, thử nghiệm, v.v.) và phần có các bản demo hoặc ảnh chụp màn hình.

Thường thì bạn cũng sẽ tìm thấy một phần cung cấp thông tin về dự án (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 là giấy phép . Những yếu tố này giúp README hoạt động vừa như một hướng dẫn nhanh cho người dùng, vừa như một tấm danh thiếp cho những người đóng góp tiềm năng.

Về mặt thiết kế, mặc dù đây là một tập tin văn bản, nhưng vẫn có rất 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à chữ in đậm để làm nổi bật các ý 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 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 thảo luận là luôn viết như thể người viết hoàn toàn không biết gì về dự án . Điều này có nghĩa là tránh giả định về kiến ​​thức sẵn có, sử dụng câu văn 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 README bất cứ khi nào có thay đổi liên quan đến 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ép . Việ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õ ràng các điều kiện mà nó có thể đượ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óp . Phầ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 tách ra thành một tệp CONTRIBUTING.md được liên kết từ tệp README.

Việc công khai thông tin của những người đóng góp và nhà phát triển cũng là một việc làm tốt . Một số dự án bao gồm các bảng với ảnh đại diện và tên được liên kết đến 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. Điều này không chỉ ghi nhận công việc của họ 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, bạn nên dành vài dòng để giải thích cách nhận trợ giúp và các kênh hỗ trợ 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, bạn cũng nên nêu rõ điều này để tránh hiểu nhầm.

Với tất cả những điều đã nêu trên, tệp README trở thành một thành phần trung tâm của bất kỳ dự án kỹ thuật số nào: nó giải thích dự án là gì, hoạt động như thế nào, ai chịu trách nhiệm bảo trì và được sử dụng trong điều kiện nào . Việc duy trì nội dung và cập nhật tệp README 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 sản phẩm của bạn.