Apa itu file README dan bagaimana cara menggunakannya dengan benar?

Jika Anda mengerjakan proyek digital, cepat atau lambat Anda akan menemukan file yang bernama... READMEMeskipun mungkin tampak seperti dokumen teks sederhana, dokumen ini jauh lebih penting daripada yang terlihat: ini adalah surat pengantar untuk proyek Anda, titik masuk pertama bagi siapa pun yang ingin mengetahui apa yang telah Anda lakukan, bagaimana cara menggunakannya, dan apakah itu sepadan dengan waktu mereka.

Dalam dunia pengembangan perangkat lunak, ilmu data, atau bahkan dalam pekerjaan akademis dan proyek kolaboratif, sebuah README ditulis dengan baik. Ini menghemat waktu Anda, mencegah kesalahan, dan memudahkan orang lain (atau bahkan diri Anda sendiri dalam beberapa bulan) untuk dengan cepat memahami tujuan proyek. Mari kita lihat lebih dekat apa itu file README, untuk apa file tersebut, apa yang harus disertakan di dalamnya, dan bagaimana cara memaksimalkannya.

Sebenarnya apa itu file README?

File README adalah sebuah dokumen teks yang menyertai proyek digital Tujuan utamanya adalah untuk menjelaskan secara jelas apa isi proyek tersebut, untuk apa proyek itu, dan bagaimana cara menggunakannya. Secara harfiah, artinya kurang lebih "baca saya," dan itulah tepatnya fungsinya: menjadi hal pertama yang dibaca seseorang ketika mereka membuka repositori, folder data, atau paket perangkat lunak.

Jenis file ini dapat disimpan dalam berbagai format. format teks: dari klasik readme.txt (teks biasa) hingga readme.doc, readme.1st atau ekstensi yang kurang umum seperti . MeFormat spesifik biasanya disesuaikan dengan sistem operasi dan program yang akan digunakan untuk menampilkannya.sehingga setiap pengguna dapat membuka dan membaca file tanpa komplikasi apa pun.

Saat ini, khususnya dalam proyek perangkat lunak dan repositori kode, format yang paling umum adalah README.mdEkstensi .md menunjukkan bahwa file tersebut ditulis dalam format tertentu. Penurunan hargaHTML adalah bahasa markup yang sangat sederhana yang memungkinkan Anda mengubah teks menjadi HTML hanya dengan menggunakan beberapa simbol untuk pemformatan. Hal ini memudahkan pemformatan konten. mudah dibaca baik dalam bentuk mentah maupun yang sudah ditampilkan di web.Selain itu, memungkinkan pembuatan judul, daftar, tautan, tabel, gambar, dan lainnya tanpa komplikasi.

README yang terstruktur dengan baik menawarkan kepada pengguna atau kontributor sebuah informasi yang bermanfaat. ringkasan proyek yang lengkap dan mudah dipahamiDokumen ini bukan dimaksudkan sebagai dokumen yang lengkap, melainkan panduan praktis: apa yang dilakukan proyek ini, mengapa proyek ini bermanfaat, bagaimana cara mulai menggunakannya, dan di mana menemukan informasi lebih lanjut jika diperlukan.

Dalam bidang data, misalnya pada repositori dataset, sangat umum bagi README (terkadang dalam format) untuk berupa readme.txt) mengumpulkan Informasi umum, kepengarangan, kata kunci, cakupan geografis dan temporal, lisensi penggunaan, dan metodologi. digunakan untuk menghasilkan atau mengumpulkan data, serta Perangkat lunak yang direkomendasikan untuk bekerja dengan mereka.

Sejarah singkat dan penggunaan standar file README

Meskipun saat ini kita kebanyakan mengaitkannya dengan platform seperti GitHub, praktik menyertakan file README dalam paket perangkat lunak berasal dari beberapa dekade yang laluTerdapat contoh-contoh yang terdokumentasi sejak pertengahan tahun 70-an, ketika program-program tersebut sudah didistribusikan dengan dokumen kecil yang menjelaskan isi dan cara penggunaannya.

Seiring waktu, praktik tersebut menjadi begitu mapan sehingga pada Standar Pemrograman GNU (Standar pengkodean GNU) file README dianggap sebagai sebuah persyaratanStandar-standar ini sangat memengaruhi ekosistem perangkat lunak bebas dan berkontribusi menjadikan file README hampir wajib dalam setiap paket perangkat lunak yang serius.

Ketika web menjadi platform standar untuk mendistribusikan perangkat lunakBanyak proyek mulai memindahkan sebagian informasi yang sebelumnya ada di README (manual, lisensi, berita, dll.) ke situs web, wiki, atau platform lainnya. paket tarball kode sumberMeskipun demikian, file README tidak pernah hilang: dalam banyak kasus, file tersebut tetap ada. ringkasan lokalmeskipun terkadang masih agak kurang lengkap jika dibandingkan dengan dokumentasi online.

Popularitas platform seperti GitHub Dan upaya dari komunitas perangkat lunak bebas yang lebih mapan telah membawa file README kembali ke garis depan. Di GitHub, misalnya, jika sebuah repositori berisi file README di direktori root, sistem akan secara otomatis menambahkannya. Secara otomatis dikonversi ke HTML dan ditampilkan di halaman beranda. dari proyek tersebut, jadi itu adalah hal pertama yang Anda lihat saat masuk.

Selain itu, gagasan tentang "file readme" terkadang digunakan dalam sebuah umum Untuk merujuk pada dokumen singkat apa pun yang menjelaskan isi folder atau proyek, meskipun nama filenya tidak persis README. Banyak proyek perangkat lunak bebas mendistribusikan serangkaian file standar bersama dengan README, masing-masing dengan fungsi yang terdefinisi dengan baik.

File-file umum yang menyertai README

Dalam proyek yang mengikuti standar seperti Standar Gnits atau yang dihasilkan dengan alat seperti GNU AutotoolsSelain file README utama, biasanya terdapat file teks lain yang melengkapi informasi proyek. Beberapa yang paling umum adalah:

• README: informasi umum tentang proyek, tujuan, dan visi keseluruhan.
• PENULIS: daftar penulis atau kolaborator utama.
• TERIMA KASIH: Ucapan terima kasih kepada orang atau lembaga yang telah membantu.
• CHANGELOG: catatan perubahan terperinci, dirancang terutama untuk pengembang.
• BERITA: catatan perubahan yang lebih ringkas dan mudah dipahami untuk pengguna akhir.
• INSTALL: petunjuk pemasangan khusus dan persyaratan teknis.
• HAK CIPTA / LISENSI: teks lisensi perangkat lunak untuk penggunaan dan distribusi.
• BUGKesalahan yang diketahui dan cara melaporkannya dengan benar.
• FAQ (Pertanyaan Umum)Pertanyaan yang sering diajukan dan jawabannya.
• SEMUADaftar tugas yang tertunda dan rencana perbaikan di masa mendatang.

Semua dokumen ini, bersama dengan README, membentuk kerangka dasar dokumentasi dari banyak paket. Dalam beberapa kasus, sebagian informasi ini diduplikasi baik di repositori maupun di situs web proyek untuk mempermudah akses dari berbagai saluran.

Peran README di GitHub dan platform serupa

Di GitHub, file README memainkan peran yang sangat penting. Pertama-tama, biasanya hal pertama yang dilihat siapa pun yang berkunjung repositori AndaJika berkas tersebut dibuat dengan baik, dalam beberapa detik akan jelas apa yang dilakukan proyek tersebut, mengapa proyek tersebut mungkin menarik, bagaimana cara menjalankannya, dan siapa yang berada di baliknya.

GitHub secara otomatis mengenali file README ketika ditempatkan di lokasi repositori tertentu. Jika Anda meletakkannya di dalam folder .githubdi direktori root atau di dalam folder docsplatform tersebut mendeteksinya dan menampilkan secara mencolok kepada pengunjung. Jika terdapat beberapa file README, GitHub mengikuti urutan prioritas: pencarian pertama di .github, lalu di akar dan akhirnya di docs.

Selain itu, jika Anda membuat repositori publik yang namanya persis sama dengan nama Anda nama pengguna Dan jika Anda menambahkan file README ke direktori root, file tersebut secara otomatis menjadi file README Anda. README ProfilIni ditampilkan di halaman pengguna Anda, memungkinkan Anda membuat bagian presentasi khusus menggunakan GitHub Flavored Markdown.

Saat file README (atau file .md lainnya) dilihat di GitHub, platform tersebut secara otomatis menghasilkan sebuah Daftar isi berdasarkan judul dokumen. Anda dapat melihat indeks ini dengan mengklik ikon "Garis Besar", yang akan memudahkan navigasi file README yang panjang dengan banyak bagian.

GitHub juga memungkinkan tautan langsung ke bagian tertentuSetiap judul secara otomatis menghasilkan jangkar; cukup arahkan kursor ke judul untuk menampilkan ikon tautan. Ini memungkinkan Anda untuk berbagi URL yang mengarah langsung ke bagian spesifik README yang ingin Anda sorot (misalnya, bagian instalasi atau kontribusi).

Ada satu detail praktis penting: demi alasan kinerja, jika README Anda melebihi... 500 KiB dari ukuran, GitHub akan memotong konten Mulai dari titik itu dan seterusnya dalam tampilan yang dirender. Oleh karena itu, disarankan untuk menyimpan README hanya untuk informasi penting dan memindahkan tutorial atau manual yang panjang ke wiki atau dokumentasi terpisah.

Format dan tautan di dalam README

Agar README mudah dipelihara dan berfungsi dengan baik baik di GitHub maupun klon lokal, disarankan untuk menggunakan tautan relatif dan jalur gambar relatif terhadap file tempat gambar tersebut berada. Jadi, misalnya, jika Anda memiliki file README di direktori root dan sebuah dokumen docs/CONTRIBUTING.mdTautan di dalam file README akan terlihat seperti ini: (docs/CONTRIBUTING.md).

Jenis tautan relatif ini berarti bahwa ketika beralih cabang atau mengkloning repositori, Rute-rute tersebut terus berfungsi dengan benar. tanpa perlu memodifikasinya. GitHub secara internal menangani transformasi jalur ini agar mengarah ke versi file yang benar berdasarkan cabang yang ditampilkan. Jalur yang diawali dengan /yang diinterpretasikan relatif terhadap akar repositori, serta operator umum seperti ./ o ../.

Penting bahwa file teks tautan Jaga agar tautan tetap dalam satu baris, karena memisahkannya menjadi beberapa baris dapat menyebabkan kerusakan. Selain itu, hindari tautan absolut ke file repositori internal, karena tautan ini dapat rusak jika URL dasar berubah atau terjadi percabangan (fork).

Mengenai ruang lingkup dokumen, perlu diingat bahwa README seharusnya hanya berisi Informasi penting untuk mulai menggunakan dan berkontribusi untuk proyek tersebut. Untuk dokumentasi yang ekstensif (manual pengguna, panduan API lengkap, dll.), akan lebih rapi jika menggunakan wiki atau sistem dokumentasi terpisah, yang menautkannya dari file README itu sendiri.

Apa sebenarnya tujuan dari file README?

Di luar teori, file README berfungsi dalam praktiknya sebagai panduan dan titik referensi awalTujuan dokumen ini bukan untuk menggantikan dokumentasi formal yang ekstensif, melainkan untuk menawarkan penjelasan yang teratur dan praktis tentang aspek-aspek terpenting dari proyek tersebut.

Di antara kegunaannya yang paling umum adalah: jelaskan tujuannya Dalam proyek tersebut, jelaskan data atau file apa yang disertakan, tunjukkan cara mulai menggunakannya, dan tentukan persyaratan teknis utama. hindari kesalahan yang disebabkan oleh penggunaan yang tidak tepatSaat banyak pengguna mengerjakan kode atau data yang sama, README yang jelas akan menghemat banyak pertanyaan berulang.

Dalam proyek bersama, terutama dalam tim besar atau komunitas sumber terbuka, README hampir merupakan sebuah komponen infrastruktur komunikasiHal ini berfungsi untuk menyelaraskan ekspektasi, menunjukkan tingkat kematangan proyek, mendefinisikan bagaimana seseorang berkontribusi, dan memperjelas dukungan apa yang ditawarkan (jika ada).

Bahkan dalam proyek pribadi, meskipun hanya Anda yang mengerjakannya, README yang ditulis dengan baik berfungsi sebagai memori jangka panjangSeiring waktu, mudah untuk melupakan keputusan, ketergantungan, atau langkah-langkah instalasi; mendokumentasikannya akan menyelamatkan Anda dari keharusan "menemukan kembali" proyek Anda sendiri beberapa bulan kemudian.

Oleh karena itu, README bukan sekadar formalitas: ini adalah alat praktis yang meningkatkan organisasi, komunikasi, dan pemeliharaan dari segala jenis proyek digital.

Kapan sebaiknya membuat file README?

Singkatnya, membuat file README adalah ide yang bagus. setiap kali ada proyek yang akan digunakan, ditinjau, atau dipelihara. oleh seseorang selain pencipta aslinya… dan itu termasuk diri Anda di masa depan. Tidak harus berupa repositori sumber terbuka yang besar: cukup memiliki beberapa kompleksitas atau konten yang menimbulkan pertanyaan.

Beberapa contoh di mana file README sangat berguna adalah: proyek web atau pemrogramanDi mana disarankan untuk menjelaskan persyaratan, proses pengembangan, perintah startup, dan lingkungan runtime. Ini juga sangat menarik dalam folder berisi data pentinguntuk mengklarifikasi apa yang diwakili oleh data tersebut, asal-usulnya, dan kemungkinan keterbatasannya.

Konteks umum lainnya adalah situs web yang dihosting di hostingyang seringkali menyertakan file README dengan petunjuk penyebaran, atau karya akademis dan teknis, di mana README dapat menjelaskan skrip, eksperimen, versi alat yang digunakan, atau cara mereproduksi hasilnya.

En proyek kolaboratifBaik internal maupun publik, file README hampir wajib. File ini membantu orang baru bergabung dengan proyek dengan lebih lancar dan berfungsi sebagai referensi bersama untuk menjaga konsistensi standar penggunaan dan kontribusi di antara semua pemangku kepentingan.

Informasi apa saja yang seharusnya terdapat dalam README yang baik?

README yang efektif tidak harus panjang, tetapi harus mencakup hal-hal berikut: terorganisir dengan baik dan sangat jelasAda beberapa informasi dasar yang hampir selalu harus disertakan, dan konten opsional lainnya yang menambah nilai tergantung pada jenis proyeknya.

Setidaknya, sebagian besar repositori dan paket yang terdokumentasi dengan baik mencakup hal-hal berikut: nama proyek, sebuah deskripsi singkat tentang tujuanringkasan isi repositori, Petunjuk penggunaan atau pemasangannya dan persyaratan penting (ketergantungan, versi bahasa minimum, sistem operasi, dll.).

Sangat disarankan juga untuk menambahkan beberapa metode kontak atau dukunganSekalipun hanya berupa email atau tautan ke bagian "Masalah" di repositori, ini memandu siapa pun yang mengalami masalah tentang di mana dan bagaimana melaporkannya, alih-alih membiarkan mereka bingung dan tidak yakin siapa yang harus dihubungi.

Selain hal-hal mendasar, seringkali bermanfaat untuk menyertakan informasi tentang hal-hal berikut: tanggal pembuatan atau versi saat ini, daftar penulis atau pihak yang bertanggung jawab, lisensi penggunaan dan pemberitahuan terkait apa pun tentang penggunaan data atau kode tersebut (misalnya, jika itu adalah versi eksperimental atau tidak cocok untuk produksi).

Urutan juga memengaruhi keterbacaan: informasi yang paling penting (apa proyeknya, untuk apa, bagaimana penggunaannya) harus muncul pertama. di awal dokumenMenyimpan detail sekunder, kredit tambahan, atau catatan sejarah untuk nanti. Dengan cara ini, seseorang yang hanya sekadar melihat-lihat dapat memperoleh gambaran yang jelas hanya dengan sekilas pandang.

Contoh isi umum file README dalam perangkat lunak.

Dalam proyek perangkat lunak, file README sering kali melangkah lebih jauh dan menyertakan beberapa blok tematik tambahan. Dalam banyak kasus, file tersebut secara singkat merangkum instruksi penyiapan, petunjuk pemasangan, petunjuk penggunaan dasar, sebuah file manifesto (jelaskan fungsi setiap folder penting) dan ringkasan lisensi.

Biasanya juga disertakan bagian yang berisi informasi tentang pengembang atau tim, berbagai cara untuk berkontribusi pada proyek, daftar kesalahan yang diketahui, dan panduan pemecahan masalah singkat untuk masalah umum. Semua ini membantu siapa pun yang mengunjungi repositori untuk mendapatkan informasi yang dibutuhkan. visi global dan praktis tanpa perlu mencari di tempat lain.

Dalam beberapa kasus, README mungkin berisi sedikit informasi. Ubah Log atau merujuk ke file CHANGELOG eksternal. Sangat umum juga untuk menyertakan bagian "Berita" atau "Apa yang Baru" yang menyoroti perubahan relevan antar versi, terutama ketika target audiens adalah pengguna akhir dan bukan pengembang.

Dalam konteks repositori akademis atau data, selain deskripsi konten, banyak templat merekomendasikan untuk mendeskripsikan hal berikut: metodologi untuk mengumpulkan atau menghasilkan data, variabel yang disertakan, rentang waktu dan geografis informasi, dan batasan-batasan yang relevan terkait penggunaan atau interpretasi.

README sebagai alat komunikasi di GitHub

Saat Anda mengunggah proyek ke GitHub, README tidak hanya menjadi dokumentasi, tetapi juga sebuah elemen komunikasi dan presentasiFaktanya, platform itu sendiri merekomendasikan penambahan README ke setiap repositori publik untuk membantu pengunjung dengan cepat memahami tentang apa proyek tersebut.

Anda dapat menggunakan README untuk menjelaskan. apa yang dilakukan proyek iniMengapa hal itu mungkin bermanfaat, bagaimana cara memulainya (misalnya, dengan bagian "Memulai"), di mana mendapatkan bantuan (masalah, forum, obrolan, dll.), dan siapa yang secara aktif memelihara kode tersebut. Semua ini memengaruhi kualitas yang dirasakan dan kepercayaan yang dihasilkan oleh repositori tersebut.

Dalam banyak kasus, pengembang menggunakan repositori GitHub mereka sebagai portofolio profesionalDalam konteks ini, README yang dirancang dengan baik sangatlah penting: README memungkinkan perekrut atau pihak lain yang berkepentingan untuk melihat sekilas ruang lingkup proyek, teknologi yang digunakan, dan metode kerja penulis.

Jika tujuan Anda bukan untuk menarik kontribusi atau mempromosikan repositori (misalnya, jika itu adalah proyek pribadi atau sangat internal), README yang sangat detail tidak wajib. Meskipun demikian, biasanya praktis untuk memelihara setidaknya satu README. dokumentasi dasar minimum untuk penggunaan pribadi dan tim.

GitHub juga menawarkan beberapa utilitas khusus terkait README: secara otomatis menghasilkan indeks, mendukung lencana dan ikon, serta memungkinkan Anda menyisipkan gambar, GIF, atau video untuk menampilkan proyek. Jika digunakan secara efektif, semua elemen ini dapat membuat README lebih efektif. lebih menarik dan lebih mudah dinavigasi.

Cara menyusun dan meningkatkan README Anda

Saat menganalisis repositori populer (misalnya, proyek dari organisasi teknologi besar atau badan antariksa), terlihat bahwa file README mereka biasanya memiliki sejumlah kesamaan. pola umummeskipun setiap proyek mempertahankan identitas visual dan kontennya masing-masing.

Biasanya ditemukan judul yang jelas dan kemungkinan gambar sampul (seperti logo atau banner untuk proyek tersebut), diikuti oleh beberapa lencana yang merangkum status proyek, lisensi, versi saat ini, atau status pengujian. Kemudian biasanya ada deskripsi proyek, sebuah bagian tentang status (stabil, dalam pengembangan, eksperimental, dll.) dan sebuah bagian dengan demonstrasi atau tangkapan layar.

Sangat umum juga untuk menemukan blok dengan akses ke proyek (tautan ke versi yang diimplementasikan, dokumentasi, dan paket yang diterbitkan), daftar teknologi yang digunakan, bagian yang didedikasikan untuk kontributor, pengembang, dan, tentu saja, lisensiElemen-elemen ini membantu README berfungsi baik sebagai panduan cepat bagi pengguna maupun sebagai kartu nama bagi calon kontributor.

Mengenai desain, meskipun kita berbicara tentang file teks, masih banyak ruang untuk membuatnya lebih mudah dibaca: gunakan judul yang terstruktur dengan baik, daftar berurutan dan tidak berurutan, tabel jika sesuai, dan Teks tebal untuk menyoroti ide-ide utama.Dalam Markdown, Anda juga dapat menyisipkan gambar, GIF, dan dekorasi kecil (seperti emoji) untuk membuatnya lebih ramah pengguna, dengan selalu mengutamakan kejelasan.

Sebuah trik yang jarang dibahas adalah selalu menulis sambil memikirkan seseorang yang Dia sama sekali tidak tahu apa pun tentang proyek tersebut.Ini berarti menghindari asumsi tentang pengetahuan sebelumnya, menggunakan bahasa yang jelas dan lugas, serta mengklarifikasi istilah teknis sejak pertama kali muncul. Dan, tentu saja, selalu memperbarui README setiap kali ada perubahan relevan dalam proyek.

Lisensi, kontribusi, dan kepengarangan

Dalam proyek sumber terbuka, bagian README yang sangat penting adalah bagian yang dikhususkan untuk... lisensiMempublikasikan kode di repositori publik tidak secara otomatis menjadikannya perangkat lunak bebas; perlu dinyatakan secara eksplisit dalam kondisi apa kode tersebut dapat dianggap sebagai perangkat lunak bebas. untuk digunakan, dimodifikasi, dan didistribusikan kembali.

Praktik yang paling umum adalah menggunakan lisensi yang sudah dikenal (MIT, Apache, GPL, Creative Commons untuk dokumentasi, dll.) dan menautkan dari file README ke file LICENSE atau COPYING repositori. Dengan cara ini, siapa pun yang tertarik akan langsung mengetahui apa yang dapat mereka lakukan dengan kode tersebut dan apa kewajiban mereka (misalnya, atribusi, berbagi secara setara, batasan tanggung jawab, dll.).

Salah satu elemen penting lainnya dalam README yang baik adalah... panduan kontribusiBagian ini menjelaskan bagaimana orang lain dapat berkontribusi pada proyek: pedoman gaya penulisan, proses pengajuan pull request, cara melaporkan bug, jenis kontribusi apa yang diterima, dan di mana pekerjaan dikoordinasikan. Terkadang informasi ini terdapat dalam file CONTRIBUTING.md terpisah yang ditautkan dari README.

Selain itu, merupakan praktik yang baik untuk membuat hal-hal tersebut terlihat. individu dan pengembang yang berkontribusiBeberapa proyek menyertakan tabel dengan avatar dan nama yang terhubung ke profil mereka, sementara yang lain hanya mencantumkan pengguna utama. Tindakan ini tidak hanya menghargai kerja keras tetapi juga mempermudah kontak langsung jika seseorang perlu berbicara dengan anggota tim tertentu.

Terakhir, ada baiknya meluangkan beberapa baris untuk menjelaskan cara mendapatkan bantuan Dan saluran apa saja yang tersedia: GitHub issues, forum, milis, obrolan, dll. Jika proyek tersebut tidak menawarkan dukungan resmi, sebaiknya hal ini juga ditunjukkan dengan jelas untuk menghindari kesalahpahaman.

Dengan semua hal di atas, file README menjadi bagian sentral dari setiap proyek digital: Dokumen ini menjelaskan apa itu, bagaimana cara kerjanya, siapa yang memeliharanya, dan dalam kondisi apa alat ini dapat digunakan.Merawat konten Anda dan selalu memperbaruinya adalah investasi kecil yang memberikan perbedaan besar dalam cara orang lain memandang dan menggunakan karya Anda.

Artikel terkait:

Cara menulis dokumentasi teknis perangkat lunak yang bermanfaat dan mudah dipelihara.

Isaac

Penulis yang bersemangat tentang dunia byte dan teknologi secara umum. Saya suka berbagi ilmu melalui tulisan, dan itulah yang akan saya lakukan di blog ini, menunjukkan kepada Anda semua hal paling menarik tentang gadget, perangkat lunak, perangkat keras, tren teknologi, dan banyak lagi. Tujuan saya adalah membantu Anda menavigasi dunia digital dengan cara yang sederhana dan menghibur.