Tạo tệp README.md cho dự án: cấu trúc chuẩn và những phần đừng bỏ sót
Công cụ dựng sẵn một tệp README.md hoàn chỉnh từ những thông tin bạn điền vào biểu mẫu: tên dự án, mô tả, danh sách tính năng, lệnh cài đặt, ví dụ sử dụng, bảng biến môi trường, phần đóng góp, giấy phép và thông tin tác giả. Khung xem trước cập nhật ngay khi gõ, và bạn tải thẳng ra tệp README.md hoặc sao chép nội dung Markdown.
Tính năng nổi bật
- Biểu mẫu điền theo từng mục, khung xem trước Markdown cập nhật ngay khi gõ
- Sáu huy hiệu chọn bằng ô đánh dấu gồm npm, giấy phép, Node.js, TypeScript, React và Next.js
- Ô danh sách tính năng theo dòng, mỗi dòng tự thành một mục gạch đầu dòng
- Ô lệnh cài đặt và ô ví dụ sử dụng đều được bọc sẵn trong khối mã
- Ô biến môi trường viết theo dạng tên bằng mô tả, tự dựng thành bảng Markdown hai cột
- Bật tắt phần hướng dẫn đóng góp gồm năm bước tạo nhánh và mở yêu cầu gộp
- Điền tên giấy phép, tên tác giả và tài khoản GitHub để tự sinh liên kết hồ sơ
- Nút sao chép toàn bộ và nút tải trực tiếp ra tệp README.md, mọi thứ chạy trên trình duyệt
README là trang bán hàng của một dự án mã nguồn
Với một kho mã trên GitHub, README là thứ duy nhất người ta đọc trước khi quyết định có dùng dự án của bạn hay không. Người ghé qua thường dành chưa tới một phút để trả lời ba câu hỏi: dự án này giải quyết vấn đề gì, cài đặt có phức tạp không, và dùng thử một lần mất bao lâu. Nếu README không trả lời được cả ba trong phần nhìn thấy đầu tiên, họ đóng tab và tìm dự án khác. Với dự án nội bộ trong công ty, README đóng vai trò khác nhưng cũng quan trọng không kém: nó là thứ giữ cho người mới vào nhóm không phải hỏi lại những câu đã hỏi mười lần, và là chỗ ghi lại các biến môi trường bắt buộc — thông tin mà nếu chỉ nằm trong đầu một người thì cả nhóm sẽ tắc khi người đó nghỉ. Vấn đề là viết README từ tệp trống rất dễ bỏ sót mục, nên có sẵn một bộ khung buộc bạn điền đủ những phần thiết yếu là cách nhanh nhất để có một tệp dùng được.
Lợi ích khi sử dụng
- Có ngay bộ khung đầy đủ thay vì ngồi trước một tệp trống
- Không bỏ sót phần biến môi trường, thứ hay bị quên nhất trong dự án nội bộ
- Xem trước Markdown ngay bên cạnh nên biết kết quả trước khi đưa vào kho mã
- Tải thẳng ra tệp đúng tên README.md, không phải tạo tệp và đổi tên thủ công
- Thống nhất cấu trúc README giữa các dự án của cùng một nhóm
Cách tạo tệp README
- 1Điền tên dự án và mô tả ngắn, phần mô tả nên nói dự án làm gì cho ai chứ không phải nó được viết bằng công nghệ gì.
- 2Đánh dấu các huy hiệu phù hợp, viết mỗi tính năng trên một dòng riêng trong ô tính năng.
- 3Điền lệnh cài đặt thật của dự án và một ví dụ sử dụng ngắn nhưng chạy được, đừng dùng đoạn mã giả.
- 4Liệt kê biến môi trường theo dạng tên biến, dấu bằng rồi mô tả; mỗi dòng sẽ thành một hàng trong bảng.
- 5Điền giấy phép, tác giả và tài khoản GitHub, rồi bấm tải về để lấy tệp README.md đặt vào thư mục gốc kho mã.
Một README tốt gồm những phần nào và xếp theo thứ tự nào
Thứ tự quan trọng gần bằng nội dung, vì người đọc quét từ trên xuống và bỏ cuộc rất sớm. Trên cùng là tên dự án và một câu mô tả duy nhất nói rõ dự án làm gì cho ai; tránh mở đầu bằng danh sách công nghệ vì người đọc chưa quan tâm tới điều đó. Ngay dưới đó nên là ảnh chụp màn hình hoặc ảnh động minh họa nếu dự án có giao diện, vì một hình cho biết nhiều hơn ba đoạn văn. Tiếp theo là hướng dẫn cài đặt và một ví dụ chạy được trong vòng vài dòng — đây là phần quyết định người ta có thử hay không. Sau đó mới tới danh sách tính năng chi tiết, cấu hình và biến môi trường, hướng dẫn phát triển tại máy, cách chạy kiểm thử, hướng dẫn đóng góp, giấy phép và thông tin liên hệ. Với README dài hơn khoảng một màn hình rưỡi, nên thêm mục lục ngay dưới phần mô tả. Nguyên tắc chung là mọi thứ người dùng cần để chạy thử phải nằm trong nửa trên, còn mọi thứ người đóng góp cần thì nằm ở nửa dưới.
Công cụ dựng ra chính xác cấu trúc gì
Tệp sinh ra bắt đầu bằng tiêu đề cấp một là tên dự án, tiếp đến là hàng huy hiệu nếu bạn có chọn, rồi tới đoạn mô tả. Sau đó lần lượt là mục tính năng dạng gạch đầu dòng, mục cài đặt với lệnh bọc trong khối mã đánh dấu ngôn ngữ bash, mục sử dụng với đoạn mã bọc trong khối đánh dấu ngôn ngữ javascript, mục biến môi trường dựng thành bảng hai cột tên biến và mô tả, mục đóng góp gồm năm bước từ tạo bản sao kho mã tới mở yêu cầu gộp, mục giấy phép, mục tác giả kèm liên kết tới hồ sơ GitHub, và cuối cùng là một dòng kêu gọi gắn sao cho kho mã. Các mục sẽ tự biến mất nếu bạn để trống ô tương ứng, trừ mục cài đặt luôn xuất hiện. Có hai chỗ bạn nên chỉnh tay sau khi tải về. Một là các tiêu đề mục đang kèm biểu tượng cảm xúc; nhiều nhóm không thích phong cách đó, và biểu tượng trong tiêu đề còn làm liên kết neo tự sinh trở nên khó đoán khi bạn muốn làm mục lục. Hai là khối mã ví dụ luôn được đánh dấu ngôn ngữ javascript, nên với dự án Python, Go hay PHP bạn phải sửa lại nhãn ngôn ngữ để phần tô màu cú pháp hiển thị đúng.
Huy hiệu hoạt động thế nào và nên giữ lại bao nhiêu cái
Huy hiệu thực chất chỉ là ảnh được nhúng bằng cú pháp ảnh của Markdown, trỏ tới một dịch vụ sinh ảnh động theo tham số trong đường dẫn. Có hai loại cần phân biệt. Loại tĩnh chỉ hiển thị chữ bạn đặt sẵn, ví dụ huy hiệu ghi tên công nghệ; loại này không phản ánh trạng thái thật nào cả, nó thuần trang trí. Loại động lấy dữ liệu thật, ví dụ huy hiệu phiên bản gói hiển thị số phiên bản mới nhất, hay huy hiệu trạng thái tích hợp liên tục hiển thị lần chạy kiểm thử gần nhất đạt hay hỏng; loại này mới thực sự có giá trị thông tin. Một lưu ý quan trọng khi dùng công cụ: mẫu huy hiệu phiên bản gói có chứa một chỗ giữ tên gói chưa được thay, nên sau khi tải về bạn phải tự thay chuỗi giữ chỗ đó bằng tên gói thật, nếu không huy hiệu sẽ hỏng. Về số lượng, ba tới năm huy hiệu là vừa; một hàng dài mười lăm huy hiệu công nghệ khiến README trông rối và đẩy phần mô tả xuống dưới màn hình đầu tiên.
Ghi tên giấy phép trong README là chưa đủ về mặt pháp lý
Đây là chỗ nhiều người hiểu nhầm. Một dòng chữ ghi dự án này dùng giấy phép MIT trong README không tạo ra hiệu lực cấp phép đầy đủ. Cách làm đúng là đặt một tệp tên LICENSE ở thư mục gốc của kho mã, chứa nguyên văn toàn bộ điều khoản của giấy phép kèm năm và tên chủ sở hữu bản quyền. GitHub tự nhận diện tệp này và hiển thị tên giấy phép ở thanh thông tin bên phải kho mã; nếu không có tệp đó thì phần đó để trống. Điều quan trọng hơn là hệ quả khi không có giấy phép nào: theo luật bản quyền mặc định, mã nguồn của bạn thuộc quyền sở hữu độc quyền của bạn, và việc công khai nó trên Internet không cho ai quyền sao chép, sửa đổi hay phân phối lại. Nhiều lập trình viên tưởng mở mã là tự động cho phép sử dụng, thực tế thì ngược lại. Ba lựa chọn phổ biến: MIT cho phép làm gần như mọi thứ miễn giữ lại thông báo bản quyền; Apache 2.0 tương tự nhưng có thêm điều khoản cấp quyền sáng chế rõ ràng; GPL yêu cầu mọi sản phẩm phái sinh cũng phải mở mã theo cùng giấy phép.
Những phần công cụ chưa có mà bạn nên thêm tay
Bộ khung này bao phủ phần lõi nhưng còn thiếu vài mục đáng thêm tùy loại dự án. Thứ nhất là ảnh chụp màn hình hoặc ảnh động minh họa cho dự án có giao diện; hãy chú ý dùng đường dẫn tuyệt đối thay vì đường dẫn tương đối, vì README còn được hiển thị trên trang gói npm và ở đó đường dẫn tương đối sẽ hỏng. Thứ hai là mục yêu cầu hệ thống ghi rõ phiên bản tối thiểu của môi trường chạy và các phần mềm phụ thuộc — thiếu mục này là nguyên nhân số một của những phiếu báo lỗi kiểu chạy không được trên máy tôi. Thứ ba là hướng dẫn chạy dự án tại máy phát triển, thường khác lệnh cài đặt dành cho người dùng cuối. Thứ tư là cách chạy bộ kiểm thử, thứ mà người muốn đóng góp cần biết ngay. Thứ năm là mục lục nếu tệp dài, và mục lộ trình phát triển nếu dự án còn đang tiến hóa. Với dự án dùng trong doanh nghiệp, nên có thêm một dòng chỉ tới nơi báo cáo lỗ hổng bảo mật riêng thay vì mở phiếu công khai.
Câu hỏi thường gặp (FAQ)
Tệp README nên đặt ở đâu trong kho mã?
Đặt ở thư mục gốc với đúng tên README.md, khi đó GitHub tự hiển thị nội dung ngay dưới danh sách tệp. GitHub cũng nhận tệp đặt trong thư mục .github hoặc docs, nhưng thư mục gốc vẫn là quy ước phổ biến nhất và cũng là nơi các công cụ khác tìm đầu tiên.
Vì sao huy hiệu phiên bản gói của tôi bị hỏng?
Vì mẫu huy hiệu đó chứa một chỗ giữ tên gói chưa được thay thế tự động. Sau khi tải tệp về, bạn phải mở ra và thay chuỗi giữ chỗ trong đường dẫn ảnh bằng tên gói thật của mình. Các huy hiệu còn lại không có tham số nên dùng được ngay.
Ghi giấy phép MIT trong README đã đủ chưa?
Chưa. Bạn cần thêm một tệp tên LICENSE ở thư mục gốc chứa nguyên văn điều khoản kèm năm và tên chủ sở hữu bản quyền. GitHub chỉ nhận diện giấy phép từ tệp đó. Không có tệp LICENSE thì theo mặc định không ai có quyền sao chép hay sửa đổi mã của bạn.
Không đặt giấy phép nào thì sao?
Theo luật bản quyền mặc định, mã vẫn thuộc quyền độc quyền của bạn dù công khai trên Internet, và người khác không có quyền dùng, sửa hay phân phối lại. Nếu bạn muốn người khác dùng được, bắt buộc phải chọn một giấy phép và đặt tệp LICENSE vào kho mã.
Nên chọn MIT, Apache 2.0 hay GPL?
MIT cho phép làm gần như mọi thứ miễn giữ lại thông báo bản quyền, phù hợp khi bạn muốn dự án được dùng rộng rãi. Apache 2.0 tương tự nhưng có điều khoản cấp quyền sáng chế rõ ràng, phù hợp với dự án có yếu tố doanh nghiệp. GPL buộc sản phẩm phái sinh cũng phải mở mã theo cùng giấy phép.
Làm sao bỏ các biểu tượng cảm xúc trong tiêu đề mục?
Mở tệp sau khi tải về và xóa chúng khỏi các dòng tiêu đề. Ngoài lý do phong cách, còn một lý do kỹ thuật: liên kết neo tự sinh cho mỗi tiêu đề được tạo từ nguyên văn dòng tiêu đề, nên có biểu tượng thì liên kết trở nên khó đoán khi bạn muốn dựng mục lục.
Khối mã ví dụ bị tô màu sai ngôn ngữ thì sửa ở đâu?
Công cụ luôn gắn nhãn javascript cho khối mã ví dụ sử dụng. Sau khi tải về, hãy đổi nhãn đó thành ngôn ngữ thật của bạn, chẳng hạn python, go, php hay ts, thì phần tô màu cú pháp trên GitHub mới hiển thị đúng. Khối lệnh cài đặt được gắn nhãn bash.
Ảnh trong README nên dùng đường dẫn tương đối hay tuyệt đối?
Nên dùng đường dẫn tuyệt đối. README của bạn không chỉ hiển thị trên GitHub mà còn xuất hiện trên trang gói npm và nhiều nơi khác, và ở những nơi đó đường dẫn tương đối tới thư mục ảnh trong kho mã sẽ không phân giải được, khiến ảnh vỡ.
README nên viết bằng tiếng Việt hay tiếng Anh?
Tùy đối tượng. Dự án mã nguồn mở hướng tới cộng đồng quốc tế nên viết tiếng Anh. Dự án nội bộ hoặc thư viện chỉ dùng trong nước thì tiếng Việt dễ đọc hơn cho cả nhóm. Một số dự án làm cả hai bằng cách tách tệp riêng và đặt liên kết chuyển đổi ở đầu.
Bảng biến môi trường nên ghi những gì?
Ghi tên biến, mô tả ngắn về công dụng, và nếu được thì thêm cột cho biết bắt buộc hay tùy chọn cùng giá trị mặc định. Tuyệt đối không ghi giá trị thật của khóa API hay mật khẩu vào đây; hãy ghi giá trị mẫu và giữ giá trị thật trong tệp cấu hình không đưa lên kho mã.
README dài bao nhiêu là vừa?
Không có con số cố định, nhưng nguyên tắc là mọi thứ người dùng cần để chạy thử phải nằm trong phần đầu, khoảng một màn hình rưỡi. Nếu tài liệu dài hơn, hãy tách phần chi tiết sang thư mục tài liệu riêng và để README làm cửa ngõ, kèm một mục lục dẫn đường.
Thông tin tôi điền có được gửi lên máy chủ không?
Không. Việc dựng nội dung Markdown, hiển thị xem trước và tạo tệp tải về đều chạy bằng JavaScript ngay trên trình duyệt của bạn. Tệp tải về cũng được tạo trong bộ nhớ trình duyệt chứ không đi qua máy chủ nào, nên dùng được với dự án nội bộ chưa công bố.
Từ khóa liên quan
- tạo readme.md online
- readme generator
- mẫu readme cho github
- cấu trúc readme chuẩn
- cách viết readme dự án
- badge shields.io
- huy hiệu github readme
- giấy phép mã nguồn mở
- license mit là gì
- apache 2.0 và gpl khác nhau
- tệp license trong repository
- markdown cho readme
- bảng biến môi trường readme
- hướng dẫn đóng góp contributing
- mục lục trong readme
- ảnh chụp màn hình trong readme
- readme cho dự án nội bộ
- tài liệu dự án phần mềm
- github repository documentation
- công cụ developer online miễn phí
