Apakah fail README dan cara menggunakannya dengan betul

Jika anda bekerja dengan projek digital, lambat laun anda akan menemui fail yang dipanggil READMEWalaupun ia mungkin kelihatan seperti dokumen teks yang mudah, ia jauh lebih penting daripada yang kelihatan: ia adalah surat lamaran untuk projek anda, titik masuk pertama bagi sesiapa sahaja yang ingin tahu apa yang telah anda lakukan, cara menggunakannya dan sama ada ia berbaloi dengan masa mereka.

Dalam dunia pembangunan perisian, sains data, atau pun dalam kerja akademik dan projek kolaboratif, README ditulis dengan baik Ia menjimatkan masa anda, mencegah kesilapan dan memudahkan orang lain (atau diri anda sendiri dalam beberapa bulan) untuk memahami tujuan projek dengan cepat. Mari kita lihat dengan lebih dekat apakah fail README itu, kegunaannya, apa yang perlu disertakan dan cara untuk memanfaatkannya sepenuhnya.

Apakah sebenarnya fail README?

Fail README ialah dokumen teks yang mengiringi projek digital Objektif utamanya adalah untuk menerangkan dengan jelas kandungan projek, tujuannya dan cara menggunakannya. Secara literal, ia bermaksud "baca saya", dan itulah fungsinya: menjadi perkara pertama yang dibaca seseorang apabila mereka membuka repositori, folder data atau pakej perisian.

Fail jenis ini boleh disimpan dalam pelbagai format format teks: daripada klasik Art of E (teks biasa) sehingga readme.doc, baca saya.1st atau sambungan yang kurang biasa seperti . MeFormat khusus biasanya disesuaikan dengan sistem pengendalian dan program yang akan dipaparkan dengannyasupaya mana-mana pengguna boleh membuka dan membaca fail tersebut tanpa sebarang komplikasi.

Hari ini, terutamanya dalam projek perisian dan repositori kod, format yang paling biasa ialah BACA.mdSambungan .md menunjukkan bahawa fail tersebut ditulis dalam Penurunan hargaHTML ialah bahasa penanda yang sangat mudah yang membolehkan anda menukar teks kepada HTML hanya menggunakan beberapa simbol untuk pemformatan. Ini memudahkan pemformatan kandungan. mudah dibaca dalam bentuk mentah dan yang telah diberikan di webselain membenarkan tajuk, senarai, pautan, jadual, imej dan banyak lagi tanpa komplikasi.

README yang berstruktur dengan baik menawarkan pengguna atau penyumbang satu ringkasan projek yang lengkap dan mudah difahamiIa bukan bertujuan untuk menjadi dokumen yang lengkap, tetapi panduan praktikal: apa yang dilakukan oleh projek ini, mengapa ia berguna, cara mula menggunakannya dan di mana untuk mendapatkan maklumat lanjut jika diperlukan.

Dalam bidang data, contohnya dalam repositori set data, adalah sangat biasa bagi README (kadangkala dalam format) untuk Art of E) mengumpul Maklumat umum, pengarang, kata kunci, liputan geografi dan temporal, lesen penggunaan dan metodologi digunakan untuk menghasilkan atau mengumpul data, serta Perisian yang disyorkan untuk bekerjasama dengan mereka.

Sejarah ringkas dan penggunaan standard fail README

Walaupun hari ini kita kebanyakannya mengaitkannya dengan platform seperti GitHub, amalan memasukkan fail README dalam pakej perisian berasal dari beberapa dekad yang laluTerdapat contoh-contoh yang didokumenkan sejak zaman pertengahan tahun 70-an, apabila program telah diedarkan dengan dokumen kecil yang menerangkan kandungan dan penggunaannya.

Lama-kelamaan, amalan ini menjadi begitu mantap sehingga pada Piawaian Pengekodan GNU (piawaian pengekodan GNU) fail README dianggap sebagai satu keperluanPiawaian-piawaian ini sangat mempengaruhi ekosistem perisian percuma dan menyumbang kepada menjadikan fail README hampir wajib dalam mana-mana pakej perisian yang serius.

Apabila web menjadi platform standard untuk mengedarkan perisianBanyak projek mula memindahkan sebahagian daripada maklumat yang sebelum ini terdapat dalam README (manual, lesen, berita, dll.) ke laman web, wiki atau pakej tarball kod sumberWalaupun begitu, fail README tidak pernah hilang: dalam banyak kes ia kekal sebagai ringkasan tempatanwalaupun kadangkala ia masih agak tidak lengkap berbanding dokumentasi dalam talian.

Populariti platform seperti GitHub Dan usaha komuniti perisian percuma yang lebih mantap telah membawa fail README kembali ke barisan hadapan. Di GitHub, sebagai contoh, jika repositori mengandungi fail README dalam direktori root, sistem akan menambahkannya secara automatik. Ia secara automatik menukar kepada HTML dan memaparkannya di halaman utama projek itu, jadi ia adalah perkara pertama yang anda lihat apabila anda masuk.

Tambahan pula, tanggapan "fail readme" kadangkala digunakan dalam generik Untuk merujuk kepada mana-mana dokumen pendek yang menerangkan kandungan folder atau projek, walaupun fail tersebut tidak dinamakan README. Banyak projek perisian percuma mengedarkan set fail standard bersama-sama dengan README, setiap satunya dengan fungsi yang ditakrifkan dengan baik.

Fail tipikal yang disertakan dengan README

Dalam projek yang mematuhi piawaian seperti Piawaian Gnits atau yang dihasilkan dengan alat seperti Alatan Auto GNUSelain README utama, adalah perkara biasa untuk mencari fail teks lain yang menambah maklumat projek. Antara yang paling biasa ialah:

• README: maklumat umum tentang projek, tujuan dan visi keseluruhan.
• PENGARANG: senarai pengarang atau kolaborator utama.
• THANKS: penghargaan kepada orang atau institusi yang telah membantu.
• BAHASA MELAYU: log perubahan terperinci, direka terutamanya untuk pembangun.
• BERITA: log perubahan yang lebih ringkas dan mudah difahami untuk pengguna akhir.
• MEMASANG: arahan pemasangan khusus dan keperluan teknikal.
• PENYALIN / LESEN: teks lesen perisian untuk kegunaan dan pengedaran.
• BUANGRalat yang diketahui dan cara melaporkannya dengan betul.
• Soalan LazimSoalan lazim dan jawapannya.
• SEMUA: senarai tugasan yang belum selesai dan penambahbaikan masa hadapan yang dirancang.

Semua dokumen ini, bersama-sama dengan borang README, rangka dokumentasi asas daripada banyak pakej. Dalam beberapa kes, sebahagian daripada maklumat ini digandakan dalam repositori dan di laman web projek untuk memudahkan akses daripada saluran yang berbeza.

Peranan README pada GitHub dan platform serupa

Di GitHub, fail README memainkan peranan yang sangat penting. Sebagai permulaan, ia biasanya perkara pertama yang dilihat oleh sesiapa sahaja lawatan itu repositori andaJika fail itu disiapkan dengan baik, dalam beberapa saat akan jelas apa yang dilakukan oleh projek itu, mengapa ia mungkin menarik minat, cara untuk memulakan dan menjalankannya, dan siapa yang bertanggungjawab di sebaliknya.

GitHub secara automatik mengenali fail README apabila ia diletakkan di lokasi repositori tertentu. Jika anda meletakkannya di dalam folder .githubdalam direktori root atau dalam folder docsplatform mengesannya dan memaparkan dengan jelas kepada pelawat. Apabila terdapat berbilang fail README, GitHub mengikuti susunan keutamaan: carian pertama dalam .github, kemudian di akar umbi dan akhirnya di docs.

Selain itu, jika anda mencipta repositori awam yang namanya sepadan dengan anda nama pengguna Dan jika anda menambah fail README pada root, fail itu secara automatik menjadi fail anda Profil READMEIa dipaparkan pada halaman pengguna anda, membolehkan anda mencipta bahagian pembentangan tersuai menggunakan GitHub Flavored Markdown.

Apabila README (atau mana-mana fail .md) dilihat di GitHub, platform tersebut secara automatik menjana Isi kandungan berdasarkan tajuk dokumen. Anda boleh melihat indeks ini dengan mengklik pada ikon "Garis Besar", yang menjadikannya lebih mudah untuk menavigasi fail README yang panjang dengan berbilang bahagian.

GitHub juga membenarkan pautan terus ke bahagian tertentuSetiap tajuk akan menjana sauh secara automatik; hanya dengan menggerakkan tetikus ke atas tajuk, ikon pautan akan dipaparkan. Ini membolehkan anda berkongsi URL yang menghala terus ke bahagian tertentu README yang ingin anda serlahkan (contohnya, bahagian pemasangan atau sumbangan).

Terdapat satu butiran praktikal yang penting: atas sebab prestasi, jika README anda melebihi 500 KB bersaiz, GitHub akan memendekkan kandungan Dari saat itu dan seterusnya dalam paparan yang dipaparkan. Oleh itu, adalah disyorkan untuk menyimpan README untuk maklumat penting dan memindahkan tutorial atau manual yang panjang ke wiki atau dokumentasi berasingan.

Format dan pautan dalam README

Untuk menjadikan README mudah diselenggara dan berfungsi dengan baik pada GitHub dan klon tempatan, adalah disyorkan untuk menggunakan pautan relatif dan laluan imej berbanding fail tempat ia berada. Jadi, sebagai contoh, jika anda mempunyai fail README dalam direktori root dan dokumen docs/CONTRIBUTING.mdPautan dalam README akan kelihatan seperti ini: (docs/CONTRIBUTING.md).

Pautan relatif jenis ini bermaksud apabila menukar cabang atau mengklon repositori, laluan terus berfungsi dengan betul tanpa perlu mengubahnya. GitHub mengendalikan transformasi dalaman laluan ini untuk menunjukkan versi fail yang betul berdasarkan cabang yang dipaparkan. Laluan bermula dengan /yang ditafsirkan relatif kepada akar repositori, serta operator biasa seperti ./ o ../.

Adalah penting bahawa teks pautan Kekalkan pautan pada satu baris, kerana memisahkannya merentasi berbilang baris boleh menyebabkannya rosak. Selain itu, elakkan pautan mutlak ke fail repositori dalaman, kerana pautan ini boleh rosak jika URL asas berubah atau fork dicipta.

Berkenaan skop dokumen tersebut, perlu diingat bahawa README hanya perlu mengandungi maklumat penting untuk mula menggunakan dan menyumbang kepada projek. Untuk dokumentasi yang meluas (manual pengguna, panduan API lengkap, dsb.), adalah lebih bersih untuk menggunakan wiki atau sistem dokumentasi berasingan, yang menghubungkannya daripada README itu sendiri.

Apakah tujuan sebenar fail README?

Di luar teori, fail README berfungsi dalam praktik sebagai panduan awal dan titik rujukanIa tidak bertujuan untuk menggantikan dokumentasi formal yang meluas, tetapi sebaliknya untuk menawarkan penjelasan yang teratur dan praktikal tentang aspek-aspek yang paling penting dalam projek ini.

Antara kegunaannya yang paling biasa ialah: jelaskan objektif projek, huraikan data atau fail yang disertakan, nyatakan cara untuk mula menggunakannya dan nyatakan keperluan teknikal utama dan mengelakkan kesilapan yang disebabkan oleh penggunaan yang tidak betulApabila berbilang pengguna bekerja pada kod atau data yang sama, README yang jelas akan menjimatkan soalan berulang yang tidak berkesudahan.

Dalam projek kongsi, terutamanya dalam pasukan besar atau komuniti sumber terbuka, README hampir merupakan komponen infrastruktur komunikasiIa berfungsi untuk menyelaraskan jangkaan, menunjukkan tahap kematangan projek, menentukan bagaimana seseorang menyumbang dan menjelaskan sokongan yang ditawarkan (jika ada).

Walaupun dalam projek peribadi, walaupun hanya anda yang akan mengerjakannya, README yang ditulis dengan baik bertindak sebagai ingatan jangka panjangLama-kelamaan, mudah untuk melupakan keputusan, kebergantungan atau langkah pemasangan; mendokumentasikannya dapat menyelamatkan anda daripada perlu "menemui semula" projek anda sendiri beberapa bulan kemudian.

Oleh itu, README bukan sekadar formaliti: ia adalah alat praktikal yang menambah baik organisasi, komunikasi dan kebolehpeliharaan bagi sebarang jenis projek digital.

Bilakah masa yang sesuai untuk mencipta fail README?

Jawapan ringkasnya ialah adalah idea yang baik untuk membuat fail README. apabila terdapat projek yang akan digunakan, disemak atau diselenggara oleh seseorang selain pencipta asal… dan itu termasuk diri anda pada masa hadapan. Ia tidak semestinya repositori sumber terbuka yang besar: ia hanya perlu mempunyai sedikit kerumitan atau kandungannya menimbulkan persoalan.

Beberapa contoh di mana fail README amat berguna ialah projek web atau pengaturcaraandi mana adalah dinasihatkan untuk menerangkan keperluan, proses pembangunan, arahan permulaan dan persekitaran masa jalan. Ia juga sangat menarik dalam folder dengan data pentinguntuk menjelaskan apa yang diwakili oleh data tersebut, asal usulnya dan kemungkinan batasannya.

Konteks tipikal lain ialah laman web yang dihoskan pada hostingyang selalunya merangkumi README dengan arahan pelaksanaan, atau kerja akademik dan teknikal, yang mana README boleh menerangkan skrip, eksperimen, versi alatan yang digunakan atau cara menghasilkan semula keputusan.

En projek kerjasamaSama ada dalaman atau awam, README hampir wajib. Ia membantu orang baharu menyertai projek dengan lebih lancar dan bertindak sebagai rujukan bersama untuk mengekalkan piawaian penggunaan dan sumbangan yang konsisten dalam kalangan semua pihak berkepentingan.

Apakah maklumat yang perlu terkandung dalam README yang baik?

README yang berkesan tidak semestinya panjang, tetapi ia perlu tersusun dengan baik dan sangat jelasTerdapat beberapa maklumat asas yang hampir selalu harus disertakan, dan kandungan pilihan lain yang menambah banyak nilai bergantung pada jenis projek.

Sekurang-kurangnya, kebanyakan repositori dan pakej yang didokumentasikan dengan baik merangkumi nama projek, yang penerangan ringkas tentang objektifringkasan kandungan repositori, Arahan untuk menggunakan atau memasangnya dan keperluan penting (kebergantungan, versi bahasa minimum, sistem pengendalian, dll.).

Ia juga sangat disyorkan untuk menambah beberapa kaedah hubungan atau sokonganWalaupun ia hanya e-mel atau pautan ke bahagian "Isu" pada repositori, ini akan membimbing sesiapa sahaja yang menghadapi masalah tentang di mana dan bagaimana untuk melaporkannya, dan bukannya membiarkan mereka hilang arah dan tidak pasti siapa yang perlu dihubungi.

Selain perkara asas, adalah lebih baik untuk memasukkan maklumat tentang tarikh atau versi penciptaan semasa, senarai pengarang atau pihak yang bertanggungjawab, gunakan lesen dan sebarang notis berkaitan tentang penggunaan data atau kod (contohnya, jika ia merupakan versi eksperimen atau tidak sesuai untuk pengeluaran).

Susunan juga mempengaruhi kebolehbacaan: maklumat yang paling penting (apa projek ini, untuk apa ia, bagaimana ia digunakan) harus dipaparkan dahulu. pada permulaan dokumenmeninggalkan butiran sekunder, kredit lanjutan atau nota sejarah untuk kemudian. Dengan cara ini, seseorang yang hanya melayari boleh mendapat gambaran yang jelas dengan sepintas lalu.

Kandungan tipikal README dalam perisian

Dalam projek perisian, fail README selalunya melangkah lebih jauh dan merangkumi beberapa blok tematik tambahan. Dalam banyak kes, fail tersebut meringkaskan secara ringkas arahan persediaan, arahan pemasangan, arahan penggunaan asas, a fail manifesto (terangkan kegunaan setiap folder penting) dan ringkasan lesen.

Ia juga biasa untuk memasukkan bahagian dengan maklumat tentang pembangun atau pasukan, cara yang mungkin untuk menyumbang kepada projek, senarai ralat yang diketahui dan panduan penyelesaian masalah ringkas untuk masalah biasa. Semua ini membantu sesiapa sahaja yang melawati repositori untuk mempunyai visi global dan praktikal tanpa perlu mencari di tempat lain.

Dalam sesetengah kes, README mungkin mengandungi sedikit Tukar Log atau tunjukkan kepada fail CHANGELOG luaran. Ia juga agak biasa untuk memasukkan bahagian "Berita" atau "Apa yang Baharu" yang menonjolkan perubahan yang berkaitan antara versi, terutamanya apabila khalayak sasaran adalah pengguna akhir dan bukannya pembangun.

Dalam konteks repositori akademik atau data, selain penerangan kandungan, banyak templat mengesyorkan penerangan metodologi untuk mengumpul atau menghasilkan data, pembolehubah yang disertakan, julat temporal dan geografi maklumat, dan sebarang batasan berkaitan penggunaan atau tafsiran.

README sebagai alat komunikasi di GitHub

Apabila anda memuat naik projek ke GitHub, README bukan sahaja menjadi dokumentasi, tetapi juga elemen komunikasi dan pembentanganMalah, platform itu sendiri mengesyorkan menambah README ke mana-mana repositori awam untuk membantu pelawat memahami projek tersebut dengan cepat.

Anda boleh menggunakan README untuk menerangkan apa yang dilakukan oleh projek ituMengapa ia mungkin berguna, cara untuk bermula (contohnya, dengan bahagian "Bermula"), tempat untuk mendapatkan bantuan (isu, forum, sembang, dll.), dan siapa yang secara aktif menyelenggara kod tersebut. Semua ini mempengaruhi kualiti yang dirasakan dan kepercayaan yang dijana oleh repositori.

Dalam banyak kes, pembangun menggunakan repositori GitHub mereka sebagai portfolio profesionalDalam konteks ini, README yang dihasilkan dengan baik memberi perbezaan yang besar: ia membolehkan perekrut atau pihak lain yang berminat melihat, sepintas lalu, skop projek, teknologi yang digunakan dan kaedah kerja pengarang.

Jika niat anda bukan untuk menarik sumbangan atau mempromosikan repositori (contohnya, jika ia merupakan projek peribadi atau sangat dalaman), README yang sangat terperinci tidak wajib. Walaupun begitu, biasanya praktikal untuk menyelenggara sekurang-kurangnya satu dokumentasi asas minimum untuk kegunaan peribadi dan pasukan.

GitHub juga menawarkan beberapa utiliti khusus yang berkaitan dengan README: ia menjana indeks secara automatik, menyokong lencana dan ikon dan membolehkan anda memasukkan imej, GIF atau video untuk mempamerkan projek. Jika digunakan dengan berkesan, semua elemen ini boleh menjadikan README lebih berkesan. lebih menarik dan lebih mudah dinavigasi.

Cara menstruktur dan menambah baik README anda

Apabila menganalisis repositori popular (contohnya, projek daripada organisasi teknologi besar atau agensi angkasa lepas), diperhatikan bahawa fail README mereka biasanya berkongsi beberapa corak biasawalaupun setiap projek mengekalkan identiti visual dan kandungannya sendiri.

Adalah perkara biasa untuk menemui tajuk yang jelas dan kemungkinan imej muka depan (seperti logo atau sepanduk untuk projek), diikuti dengan beberapa lencana yang meringkaskan status projek, lesen, versi semasa atau status ujian. Kemudian biasanya terdapat penerangan projek, bahagian tentang status (stabil, dalam pembangunan, eksperimen, dsb.) dan bahagian dengan demonstrasi atau tangkapan skrin.

Ia juga sangat biasa untuk menemui blok dengan akses kepada projek (pautan ke versi yang digunakan, dokumentasi dan pakej yang diterbitkan), senarai teknologi yang digunakan, bahagian yang dikhaskan untuk penyumbang, pembangun dan, sudah tentu, lesenElemen-elemen ini membantu README berfungsi sebagai panduan ringkas untuk pengguna dan sebagai kad perniagaan untuk bakal penyumbang.

Berkenaan reka bentuk, walaupun kita bercakap tentang fail teks, terdapat banyak ruang untuk menjadikannya lebih mudah dibaca: gunakan tajuk yang berstruktur dengan baik, senarai tertib dan tidak tertib, jadual jika sesuai, dan Teks tebal untuk menyerlahkan idea utamaDalam Markdown, anda juga boleh memasukkan imej, GIF dan hiasan kecil (seperti emoji) untuk menjadikannya lebih mesra pengguna, dengan sentiasa mengutamakan kejelasan.

Satu helah yang sedikit dibincangkan adalah dengan sentiasa menulis sambil memikirkan seseorang yang Dia langsung tidak tahu apa-apa tentang projek itu.Ini bermakna mengelakkan andaian tentang pengetahuan terdahulu, menggunakan bahasa yang jelas dan terus terang, dan menjelaskan istilah teknikal pada kali pertama ia muncul. Dan, sudah tentu, memastikan README dikemas kini apabila terdapat perubahan yang berkaitan dalam projek.

Lesen, sumbangan dan pengarangan

Dalam projek sumber terbuka, bahagian README yang amat penting ialah bahagian yang dikhaskan untuk lesenKod penerbitan dalam repositori awam tidak secara automatik menjadikannya perisian percuma; adalah perlu untuk menyatakan secara eksplisit di bawah syarat-syarat apa ia boleh dianggap sebagai perisian percuma. untuk digunakan, diubah suai dan diagihkan semula.

Amalan paling biasa adalah menggunakan lesen yang terkenal (MIT, Apache, GPL, Creative Commons untuk dokumentasi, dll.) dan memautkan daripada fail README ke fail LESEN atau PENYALIN repositori. Dengan cara ini, sesiapa yang berminat akan mengetahui dengan segera apa yang boleh mereka lakukan dengan kod tersebut dan apakah kewajipan mereka (contohnya, atribusi, perkongsian sama, batasan liabiliti, dll.).

Satu lagi blok utama dalam README matang ialah panduan sumbanganBahagian ini menerangkan bagaimana orang lain boleh menyumbang kepada projek ini: garis panduan gaya, proses untuk menghantar permintaan tarik, cara melaporkan pepijat, jenis sumbangan yang diterima dan di mana kerja diselaraskan. Kadangkala maklumat ini terkandung dalam fail CONTRIBUTING.md berasingan yang dipautkan daripada README.

Ia juga merupakan amalan yang baik untuk menunjukkan individu dan pembangun yang menyumbangSesetengah projek merangkumi jadual dengan avatar dan nama yang dipautkan ke profil mereka, sementara yang lain hanya menyenaraikan pengguna utama. Gerak isyarat ini bukan sahaja mengiktiraf hasil kerja tetapi juga memudahkan hubungan langsung jika seseorang perlu bercakap dengan ahli pasukan tertentu.

Akhir sekali, adalah wajar untuk mendedikasikan beberapa baris untuk menerangkan cara mendapatkan bantuan Dan saluran apa yang wujud: isu GitHub, forum, senarai mel, sembang, dll. Jika projek itu tidak menawarkan sokongan rasmi, adalah sah untuk menunjukkan perkara ini dengan jelas bagi mengelakkan salah faham.

Dengan semua perkara di atas, fail README menjadi bahagian penting dalam mana-mana projek digital: Ia menerangkan apa itu, bagaimana ia berfungsi, siapa yang menyelenggaranya, dan dalam keadaan apa ia boleh digunakan.Menjaga kandungan anda dan memastikannya dikemas kini merupakan pelaburan kecil yang memberi perbezaan besar terhadap cara orang lain melihat dan menggunakan karya anda.