Panduan proyek

Templat README GitHub untuk proyek sumber terbuka

README GitHub yang berguna menjawab empat pertanyaan dengan cepat: apa fungsi proyek ini, untuk siapa, bagaimana mencobanya, dan di mana mencari bantuan? Gunakan templat Markdown berikut sebagai titik awal, lalu ganti setiap isian dengan informasi yang sudah Anda periksa terhadap proyek.

Tim editorial GitHubStart · Diperbarui

Salin templat README Markdown ini

Ini adalah templat awal yang disusun sebagai panduan, bukan contoh perangkat lunak yang berfungsi. Ganti teks dalam kurung siku, periksa keberadaan berkas rujukan, dan hapus bagian yang tidak relevan. Baris instalasi dan eksekusi berikut berupa komentar agar perintah isian tidak dapat dijalankan tanpa sengaja.

# [Nama proyek]

[Satu kalimat: masalah, pengguna sasaran, dan hasilnya.]

## Contoh
[Tampilkan satu masukan kecil dan keluaran yang diharapkan, atau tambahkan tangkapan layar.]

## Mulai cepat
Persyaratan: [lingkungan eksekusi/versi dan layanan yang diperlukan].

```sh
# Ganti dengan perintah instalasi yang telah Anda verifikasi.
# Ganti dengan perintah paling sederhana yang menghasilkan manfaat.
```

Hasil yang diharapkan: [apa yang seharusnya dilihat pembaca].

## Konfigurasi
[Pengaturan wajib, nilai contoh yang aman, dan tempat menyimpan rahasia.]

## Kapan digunakan
- [Kasus penggunaan konkret]
- [Kasus penggunaan kedua]

## Keterbatasan
[Masukan yang tidak didukung, kematangan, batas kinerja atau platform.]

## Dokumentasi dan bantuan
[Tautkan dokumentasi dan jelaskan tempat mengajukan pertanyaan.]

## Berkontribusi
Lihat [CONTRIBUTING.md](CONTRIBUTING.md).
Laporkan masalah yang dapat direproduksi melalui tab Issues repositori.

## Lisensi
Lihat [LICENSE](LICENSE).

Sesuaikan contoh dengan jenis repositori

Untuk alat baris perintah, tampilkan berkas masukan, perintah, dan keluaran singkat. Untuk pustaka, tampilkan contoh impor dan pemanggilan lengkap yang paling sederhana, termasuk nilai kembalian yang diharapkan. Untuk aplikasi web, tampilkan alur kerja utama dan jelaskan apakah tersedia demo yang dihosting atau penyiapan lokal.

Hindari menjadikan tangkapan layar sebagai satu-satunya penjelasan API: pembaca harus dapat menyalin kode. Sebaliknya, aplikasi visual dapat terbantu oleh tangkapan layar dengan deskripsi jelas tentang tindakan pengguna. Gunakan contoh nyata dari versi yang sedang Anda distribusikan.

  • Pustaka: instalasi, lingkungan eksekusi yang didukung, dan satu pemanggilan fungsi lengkap.
  • CLI: masukan, perintah, keluaran, dan cara kesalahan dilaporkan.
  • Aplikasi web: tautan demo atau penyiapan lokal, konfigurasi, dan tangkapan layar tugas utama.
  • Kumpulan data: asal-usul, format, lisensi, dan contoh rekaman kecil.

Periksa README sebelum membagikannya

Coba panduan mulai cepat di lingkungan bersih, bukan mesin yang sudah dikonfigurasi untuk pengembangan. Periksa apakah diperlukan paket global yang tidak disebutkan, registri privat, atau berkas lokal. Jika penyiapan memerlukan akun atau layanan berbayar, nyatakan sebelum perintah pertama.

Buka tautan dokumentasi dan gambar dari halaman repositori. Pastikan nama berkas kontribusi dan lisensi sesuai dengan repositori, lalu hapus tautan rusak. README singkat dan akurat lebih baik daripada templat yang tampak mengesankan tetapi penuh janji yang belum diterapkan.

  • Hapus isian dan klaim tanpa dukungan.
  • Jangan masukkan token asli, kata sandi, atau URL privat ke contoh.
  • Periksa bahwa keluaran yang diharapkan cocok dengan versi yang diterbitkan.
  • Beri tahu pembaca informasi yang perlu disertakan saat melaporkan masalah.

Gunakan README sebagai ringkasan peluncuran

Setelah melengkapi templat, ambil pengantar singkat: satu kalimat tentang masalah, satu contoh hasil, dan satu tautan untuk mencobanya. Itulah titik awal posting komunitas. Pertahankan README asli sebagai sumber terperinci, dan sesuaikan setiap pengantar dengan pembaca, alih-alih mengulang paragraf promosi di mana-mana.

Pertanyaan umum

Apakah ini README repositori atau README profil?

Templat ini untuk repositori perangkat lunak. README profil memperkenalkan seseorang dan memerlukan bagian berbeda, seperti pekerjaan dan preferensi kontaknya.

Haruskah saya menambahkan lencana bintang di bagian atas?

Hanya jika membantu pembaca. Pastikan tujuan dan panduan mulai cepat tetap menonjol. Lencana tidak menggantikan penjelasan tentang fungsi proyek.

Bisakah templat ini digunakan untuk proyek privat?

Bisa. Ganti tautan dukungan publik dengan saluran bantuan tim yang sebenarnya, jelaskan persyaratan akses, dan jangan masukkan kredensial ke dokumen.

Referensi