Sao chép mẫu Markdown README này
Đây là mẫu khởi đầu được biên soạn, không phải ví dụ phần mềm hoạt động. Thay nội dung trong ngoặc vuông, kiểm tra các tệp được tham chiếu có tồn tại và xóa mục không phù hợp. Các dòng cài đặt và chạy bên dưới là chú thích để tránh vô tình thực thi lệnh giữ chỗ.
# [Tên dự án]
[Một câu: vấn đề, người dùng mục tiêu và kết quả.]
## Ví dụ
[Đưa ra một đầu vào nhỏ và đầu ra mong đợi, hoặc thêm ảnh chụp màn hình.]
## Bắt đầu nhanh
Yêu cầu: [môi trường chạy/phiên bản và các dịch vụ cần thiết].
```sh
# Thay bằng lệnh cài đặt đã được kiểm chứng.
# Thay bằng lệnh ngắn nhất tạo ra kết quả hữu ích.
```
Kết quả mong đợi: [những gì độc giả sẽ thấy].
## Cấu hình
[Các thiết lập bắt buộc, giá trị mẫu an toàn và nơi lưu thông tin bí mật.]
## Khi nào nên dùng
- [Một tình huống sử dụng cụ thể]
- [Tình huống sử dụng thứ hai]
## Hạn chế
[Đầu vào không hỗ trợ, độ hoàn thiện, giới hạn hiệu năng hoặc nền tảng.]
## Tài liệu và trợ giúp
[Liên kết tài liệu và giải thích nơi đặt câu hỏi.]
## Đóng góp
Xem [CONTRIBUTING.md](CONTRIBUTING.md).
Báo vấn đề có thể tái hiện qua thẻ Issues của kho mã.
## Giấy phép
Xem [LICENSE](LICENSE).Điều chỉnh ví dụ theo loại kho mã
Với công cụ dòng lệnh, trình bày tệp đầu vào, lệnh và đầu ra ngắn. Với thư viện, đưa ra ví dụ nhập và gọi nhỏ nhất nhưng đầy đủ, kèm giá trị trả về mong đợi. Với ứng dụng web, trình bày luồng thao tác chính và giải thích có bản demo trực tuyến hay cách cài đặt cục bộ hay không.
Tránh chỉ dùng ảnh chụp màn hình để giải thích API: độc giả cần sao chép được mã. Ngược lại, ứng dụng trực quan có thể hưởng lợi từ ảnh chụp kèm mô tả rõ người dùng đang làm gì. Dùng ví dụ thực tế từ phiên bản bạn đang phân phối.
- Thư viện: cài đặt, môi trường chạy được hỗ trợ và một lời gọi hàm đầy đủ.
- CLI: đầu vào, lệnh, đầu ra và cách báo lỗi.
- Ứng dụng web: liên kết demo hoặc cài đặt cục bộ, cấu hình và ảnh chụp tác vụ chính.
- Tập dữ liệu: nguồn gốc, định dạng, giấy phép và một bản ghi mẫu nhỏ.
Kiểm tra README trước khi chia sẻ
Thử hướng dẫn bắt đầu nhanh trong môi trường sạch thay vì máy đã cấu hình để phát triển. Kiểm tra xem có cần gói toàn cục chưa khai báo, kho đăng ký gói riêng tư hay tệp cục bộ không. Nếu thiết lập cần tài khoản hoặc dịch vụ trả phí, hãy nói rõ trước lệnh đầu tiên.
Mở liên kết tài liệu và hình ảnh từ trang kho mã. Xác nhận tên tệp hướng dẫn đóng góp và giấy phép khớp với kho mã, rồi xóa liên kết hỏng. README ngắn và chính xác tốt hơn mẫu trông ấn tượng nhưng đầy lời hứa chưa được thực hiện.
- Xóa nội dung giữ chỗ và tuyên bố không có cơ sở.
- Không đưa token thật, mật khẩu và URL riêng tư vào ví dụ.
- Kiểm tra đầu ra mong đợi có khớp phiên bản đã phát hành không.
- Cho độc giả biết cần cung cấp gì khi báo lỗi.
Dùng README làm cơ sở giới thiệu khi ra mắt
Sau khi hoàn thành mẫu, rút ra phần giới thiệu ngắn: một câu về vấn đề, một ví dụ kết quả và một liên kết để dùng thử. Đó là điểm khởi đầu cho bài đăng cộng đồng. Giữ README gốc làm nguồn thông tin chi tiết và điều chỉnh từng lời giới thiệu theo độc giả, thay vì lặp lại một đoạn quảng bá ở khắp nơi.
Câu hỏi thường gặp
Đây là README kho mã hay README hồ sơ cá nhân?
Mẫu này dành cho kho mã phần mềm. README hồ sơ giới thiệu một người và cần những mục khác, như công việc của họ và cách liên hệ mong muốn.
Có nên thêm huy hiệu sao ở đầu không?
Chỉ thêm nếu có ích cho độc giả. Giữ mục đích và phần bắt đầu nhanh ở vị trí nổi bật. Huy hiệu không thay thế được lời giải thích dự án làm gì.
Có thể dùng mẫu cho dự án riêng tư không?
Có. Thay liên kết hỗ trợ công khai bằng kênh trợ giúp thực tế của nhóm, giải thích yêu cầu truy cập và không đưa thông tin xác thực vào tài liệu.