Ano ang mga README file at kung paano gamitin ang mga ito nang maayos

Kung nagtatrabaho ka sa mga digital na proyekto, maya-maya ay makakakita ka ng isang file na tinatawag na READMEBagama't maaaring mukhang isang simpleng dokumentong teksto, mas mahalaga ito kaysa sa tila lumalabas: ito ang cover letter para sa iyong proyekto, ang unang pasukan para sa sinumang gustong malaman kung ano ang iyong nagawa, kung paano ito gamitin, at kung sulit ba ang kanilang oras.

Sa mundo ng pagbuo ng software, agham ng datos, o maging sa gawaing akademiko at mga proyektong kolaboratibo, isang Mahusay na pagkakasulat ng README Nakakatipid ito ng oras, nakakaiwas sa mga pagkakamali, at ginagawang mas madali para sa iba (o kahit sa iyong sarili sa loob ng ilang buwan) na mabilis na maunawaan ang layunin ng proyekto. Tingnan natin nang mas malapitan kung ano ang mga README file, para saan ang mga ito, ano ang mga dapat nilang isama, at kung paano masulit ang mga ito.

Ano nga ba ang isang README file?

Ang isang README file ay isang dokumentong teksto na kasama ng isang digital na proyekto Ang pangunahing layunin nito ay malinaw na ipaliwanag kung ano ang nilalaman ng proyekto, para saan ito, at kung paano ito gamitin. Sa literal na pagsasalin, ito ay parang "basahin mo ako," at iyon mismo ang tungkulin nito: ang maging unang bagay na binabasa ng isang tao kapag nagbukas sila ng isang repository, isang data folder, o isang software package.

Maaaring i-save ang ganitong uri ng file sa iba't ibang paraan mga format ng teksto: mula sa klasiko readme.txt (payak na teksto) hanggang sa readme.doc, readme.1st o mga hindi gaanong karaniwang extension tulad ng . Sarili koAng partikular na pormat ay karaniwang iniaangkop sa operating system at ang programang ipapakita nitopara mabuksan at mabasa ng sinumang user ang file nang walang anumang komplikasyon.

Ngayon, lalo na sa mga proyekto ng software at mga repositoryo ng code, ang pinakakaraniwang format ay README.mdAng extension na .md ay nagpapahiwatig na ang file ay nakasulat sa MarkdownAng HTML ay isang napakasimpleng markup language na nagbibigay-daan sa iyong i-convert ang teksto sa HTML gamit lamang ang ilang simbolo para sa pag-format. Ginagawa nitong mas madali ang pag-format ng nilalaman. madaling basahin kapwa sa hilaw at nai-render na anyo sa isang webbukod pa sa pagpapahintulot sa mga pamagat, listahan, link, talahanayan, larawan at higit pa nang walang mga komplikasyon.

Ang isang mahusay na istrukturang README ay nag-aalok sa gumagamit o kontribyutor ng kumpleto at madaling maunawaang buod ng proyektoHindi ito nilayong maging isang kumpletong dokumento, kundi isang praktikal na gabay: ano ang ginagawa ng proyekto, bakit ito kapaki-pakinabang, paano ito sisimulang gamitin at kung saan makakahanap ng karagdagang impormasyon kung kinakailangan.

Sa larangan ng datos, halimbawa sa mga repositoryo ng dataset, karaniwan na ang README (minsan ay nasa format) ay readme.txt) mangolekta Pangkalahatang impormasyon, pagiging awtor, mga keyword, saklaw na heograpikal at temporal, lisensya sa paggamit at metodolohiya ginagamit upang makabuo o mangolekta ng datos, gayundin ang Inirerekomendang software para sa pakikipagtulungan sa kanila.

Isang maikling kasaysayan at karaniwang paggamit ng mga README file

Bagama't ngayon ay kadalasang iniuugnay natin ang mga ito sa mga platform tulad ng GitHub, ang kaugalian ng pagsasama ng README file sa mga software package ay nagmumula sa mga dekada na ang nakalipasMay mga dokumentadong halimbawa na nagmula pa noong kalagitnaan ng dekada 70, noong ang mga programa ay ipinamamahagi na kasama ng isang maliit na dokumento na nagpapaliwanag ng kanilang nilalaman at gamit.

Sa paglipas ng panahon, ang kasanayan ay naging matatag na kaya noong Mga Pamantayan sa Pagkokodigo ng GNU (mga pamantayan ng GNU coding) ang README file ay itinuturing na isang pangangailanganAng mga pamantayang ito ay lubos na nakaimpluwensya sa ekosistema ng libreng software at nag-ambag sa paggawa ng README file na halos mandatory sa anumang seryosong pakete ng software.

Nang ang web ay naging karaniwang plataporma para sa pamamahagi ng softwareMaraming proyekto ang nagsimulang maglipat ng ilan sa impormasyong dating nasa README (mga manwal, lisensya, balita, atbp.) patungo sa mga website, wiki, o sa pakete ng tarball ng source codeGayunpaman, ang README file ay hindi kailanman nawala: sa maraming pagkakataon ay nanatili itong lokal na buodbagama't kung minsan ay medyo hindi pa rin ito kumpleto kumpara sa online na dokumentasyon.

Ang katanyagan ng mga platform tulad ng GitHub At ang mga pagsisikap ng mas matatag na mga komunidad ng libreng software ay nagbalik sa mga README file sa unahan. Sa GitHub, halimbawa, kung ang isang repository ay naglalaman ng README file sa root directory, awtomatikong idadagdag ito ng system. Awtomatiko itong nagko-convert sa HTML at ipinapakita ito sa home page ng proyekto, kaya ito ang unang bagay na makikita mo pagpasok mo.

Bukod pa rito, ang konsepto ng isang "readme file" ay minsang ginagamit sa isang pangkaraniwan Upang tumukoy sa anumang maikling dokumento na nagpapaliwanag ng mga nilalaman ng isang folder o proyekto, kahit na ang file ay hindi eksaktong pinangalanang README. Maraming libreng proyekto ng software ang namamahagi ng isang karaniwang hanay ng mga file kasama ng README, bawat isa ay may mahusay na tinukoy na function.

Karaniwang mga file na kasama ng isang README

Sa mga proyektong sumusunod sa mga pamantayan tulad ng Mga Pamantayan ng Gnits o iyong mga nabuo gamit ang mga kagamitan tulad ng Mga GNU AutotoolBukod sa pangunahing README, karaniwan ding makakahanap ng iba pang mga text file na pandagdag sa impormasyon ng proyekto. Ang ilan sa mga pinakakaraniwan ay:

• README: pangkalahatang impormasyon tungkol sa proyekto, layunin at pangkalahatang pananaw.
• MGA AUTHORS: listahan ng mga pangunahing may-akda o mga kolaborador.
• THANKS: pagkilala sa mga tao o institusyong tumulong.
• CHANGELOG: detalyadong talaan ng pagbabago, na pangunahing idinisenyo para sa mga developer.
• BALITA: isang mas maigsi at mas madaling maunawaang talaan ng pagbabago para sa mga end user.
• INSTALL: mga partikular na tagubilin sa pag-install at mga teknikal na kinakailangan.
• PAGKOPYA / LISENSYA: teksto ng lisensya ng software para sa paggamit at pamamahagi.
• TUMBOKMga kilalang pagkakamali at mga paraan upang maiulat ang mga ito nang tama.
• FAQMga madalas itanong at ang kanilang mga sagot.
• LAHAT: listahan ng mga nakabinbing gawain at mga nakaplanong pagpapabuti sa hinaharap.

Ang lahat ng mga dokumentong ito, kasama ang README, form ang balangkas ng pangunahing dokumentasyon ng maraming pakete. Sa ilang mga kaso, ang ilan sa impormasyong ito ay kinokopya kapwa sa repositoryo at sa website ng proyekto upang mapadali ang pag-access mula sa iba't ibang mga channel.

Ang papel ng README sa GitHub at mga katulad na platform

Sa GitHub, ang README file ay gumaganap ng isang partikular na mahalagang papel. Bilang panimula, kadalasan ito ay ang unang bagay na makikita ng sinuman na bumibisita ang iyong imbakanKung maayos ang pagkakagawa ng file, sa loob ng ilang segundo ay magiging malinaw kung ano ang ginagawa ng proyekto, kung bakit ito maaaring maging interesante, kung paano ito patakbuhin, at kung sino ang nasa likod nito.

Awtomatikong kinikilala ng GitHub ang README file kapag nakalagay ito sa ilang partikular na lokasyon ng repository. Kung ilalagay mo ito sa folder .github, Sa direktoryo ng ugat o sa folder docsnatutukoy ito ng plataporma at kitang-kitang ipinapakita sa mga bisita. Kapag mayroong maraming README file, sinusunod ng GitHub ang isang pagkakasunud-sunod ng priyoridad: unang paghahanap sa .github, pagkatapos ay sa ugat at sa wakas ay sa docs.

Bukod pa rito, kung gagawa ka ng pampublikong repositoryo na ang pangalan ay eksaktong tumutugma sa iyong username At kung magdadagdag ka ng README file sa root directory, awtomatikong magiging README file mo ang file na iyon. README ng ProfileIto ay ipinapakita sa iyong pahina ng gumagamit, na nagbibigay-daan sa iyong lumikha ng isang pasadyang seksyon ng presentasyon gamit ang GitHub Flavored Markdown.

Kapag tiningnan ang isang README (o anumang .md file) sa GitHub, awtomatikong bubuo ang platform ng isang Talaan ng nilalaman batay sa mga pamagat ng dokumento. Maaari mong tingnan ang indeks na ito sa pamamagitan ng pag-click sa icon na "Outline", na ginagawang mas madali ang pag-navigate sa mahahabang README file na may maraming seksyon.

Pinapayagan din ng GitHub ang direktang mag-link sa mga partikular na seksyonAwtomatikong bubuo ng anchor ang bawat heading; ang pag-hover lang sa ibabaw ng pamagat ay magpapakita ng icon ng link. Nagbibigay-daan ito sa iyong magbahagi ng mga URL na direktang nakaturo sa partikular na seksyon ng README na gusto mong i-highlight (halimbawa, ang seksyon ng instalasyon o mga kontribusyon).

May isang mahalagang praktikal na detalye: para sa mga kadahilanan ng pagganap, kung ang iyong README ay lumampas sa 500 KB ng laki, GitHub puputulin ang nilalaman Mula sa puntong iyon, sa na-render na view. Samakatuwid, inirerekomenda na ireserba ang README para sa mahahalagang impormasyon at ilipat ang mahahabang tutorial o manwal sa mga wiki o hiwalay na dokumentasyon.

Format at mga link sa loob ng isang README

Para madaling mapanatili ang README at gumana nang maayos sa GitHub at mga lokal na clone, inirerekomendang gamitin ang mga kamag-anak na link at mga path ng imahe kaugnay ng file kung saan sila matatagpuan. Kaya, halimbawa, kung mayroon kang README file sa root directory at isang dokumento docs/CONTRIBUTING.mdAng link sa loob ng README ay magiging ganito ang hitsura: (docs/CONTRIBUTING.md).

Ang ganitong uri ng relatibong link ay nangangahulugan na kapag nagpapalit ng mga sangay o nagko-clone ng repository, ang mga ruta ay patuloy na gumagana nang tama nang hindi kinakailangang baguhin ang mga ito. Panloob na binabago ng GitHub ang mga path na ito upang tumuro sa tamang bersyon ng file batay sa ipinapakitang branch. Ang mga path ay nagsisimula sa /na binibigyang-kahulugan kaugnay ng repository root, pati na rin ang mga karaniwang operator tulad ng ./ o ../.

Mahalaga na ang teksto ng link Panatilihin ang link sa iisang linya, dahil ang paghahati nito sa maraming linya ay maaaring magdulot ng aberya. Bukod pa rito, iwasan ang mga ganap na link sa mga internal repository file, dahil maaaring masira ang mga ito kung magbabago ang base URL o kung gagawa ng fork.

Tungkol sa saklaw ng dokumento, mahalagang tandaan na ang README ay dapat lamang maglaman ng ang mahahalagang impormasyon upang simulan ang paggamit at pag-ambag sa proyekto. Para sa malawak na dokumentasyon (mga manwal ng gumagamit, kumpletong gabay sa API, atbp.), mas malinis na gumamit ng wiki o isang hiwalay na sistema ng dokumentasyon, na nag-uugnay dito mula mismo sa README.

Ano ang tunay na layunin ng isang README file?

Higit pa sa teorya, ang README file ay gumagana sa praktika bilang paunang gabay at punto ng sanggunianHindi ito nilayong palitan ang malawak na pormal na dokumentasyon, kundi upang mag-alok ng maayos at praktikal na paliwanag sa mga pinakamahalagang aspeto ng proyekto.

Kabilang sa mga pinakakaraniwang gamit nito ay: ipaliwanag ang layunin ng proyekto, ilarawan kung anong datos o mga file ang kasama rito, ipahiwatig kung paano ito sisimulang gamitin, at tukuyin ang mga pangunahing teknikal na kinakailangan at maiwasan ang mga pagkakamaling dulot ng maling paggamitKapag maraming user ang nagtatrabaho sa parehong code o data, ang isang malinaw na README ay nakakatipid ng walang katapusang paulit-ulit na mga tanong.

Sa mga proyektong pinagsasaluhan, lalo na sa malalaking pangkat o mga komunidad na open source, ang README ay halos isang bahagi ng imprastraktura ng komunikasyonNagsisilbi itong ihanay ang mga inaasahan, ipahiwatig ang antas ng kapanahunan ng proyekto, tukuyin kung paano nakakatulong ang isang tao, at linawin kung anong suporta ang iniaalok (kung mayroon man).

Kahit sa mga personal na proyekto, kahit ikaw lang ang gagawa ng mga ito, ang isang mahusay na nakasulat na README ay nagsisilbing Pangmatagalang alaalaSa paglipas ng panahon, madaling makalimutan ang mga desisyon, dependency, o mga hakbang sa pag-install; ang pagkakaroon nito ng dokumentasyon ay makakapagtipid sa iyo mula sa pangangailangang "muling tuklasin" ang sarili mong proyekto pagkalipas ng ilang buwan.

Samakatuwid, ang README ay hindi lamang isang pormalidad: ito ay isang praktikal na kasangkapan na nagpapabuti organisasyon, komunikasyon at pagpapanatili ng anumang uri ng digital na proyekto.

Kailan angkop na gumawa ng README file?

Ang maikling sagot ay magandang ideya na gumawa ng README file. tuwing may proyektong gagamitin, susuriin, o pananatilihin ng ibang tao bukod sa orihinal na lumikha… at kasama na riyan ang iyong sarili sa hinaharap. Hindi nito kailangang maging isang napakalaking open-source na repositoryo: kailangan lang nitong magkaroon ng kaunting komplikasyon o para magdulot ng mga katanungan ang nilalaman.

Ang ilang halimbawa kung saan ang isang README file ay lalong kapaki-pakinabang ay ang mga proyekto sa web o programmingkung saan ipinapayong ipaliwanag ang mga kinakailangan, proseso ng pag-develop, mga utos sa pagsisimula, at ang kapaligiran ng runtime. Kawili-wili rin ito sa mga folder na may mahahalagang datosupang linawin kung ano ang kinakatawan ng datos na iyon, ang pinagmulan nito at mga posibleng limitasyon.

Ang iba pang karaniwang konteksto ay ang mga website na naka-host sa isang hostingna kadalasang may kasamang README na may mga tagubilin sa pag-deploy, o ang mga gawaing akademiko at teknikal, kung saan maaaring ilarawan ng README ang mga script, eksperimento, bersyon ng mga tool na ginamit, o kung paano kopyahin ang mga resulta.

En mga proyekto ng pagtutulunganPanloob man o pampubliko, halos mandatory ang README. Nakakatulong ito sa mga bagong tao na sumali sa proyekto nang mas maayos at nagsisilbing ibinahaging sanggunian upang mapanatili ang pare-parehong pamantayan sa paggamit at kontribusyon sa lahat ng stakeholder.

Anong impormasyon ang dapat taglayin ng isang mahusay na README?

Hindi kailangang mahaba ang isang epektibong README, ngunit kailangan itong maging maayos at napakalinawMay ilang pangunahing impormasyon na halos palaging dapat kasama, at iba pang opsyonal na nilalaman na nagdaragdag ng malaking halaga depende sa uri ng proyekto.

Sa pinakamababa, karamihan sa mga mahusay na dokumentadong repositoryo at pakete ay kinabibilangan ng pangalan ng proyekto, A maikling paglalarawan ng layuninisang buod ng mga nilalaman ng imbakan, ang Mga tagubilin para sa paggamit o pag-install nito at ang mga mahahalagang kinakailangan (mga dependency, minimum na bersyon ng wika, operating system, atbp.).

Lubos din na inirerekomenda na magdagdag ng ilang paraan ng pakikipag-ugnayan o suportaKahit email lang o link papunta sa seksyong "Mga Isyu" ng repository, gagabayan nito ang sinumang makakaranas ng problema kung saan at paano irereport ang mga ito, sa halip na iwan silang nalilito at hindi sigurado kung sino ang kokontakin.

Bukod sa mga pangunahing kaalaman, kadalasang nakakatulong na magsama ng impormasyon tungkol sa petsa ng paglikha o bersyon kasalukuyan, ang listahan ng mga may-akda o mga responsableng partido, ang gumamit ng lisensya at anumang kaugnay na mga abiso tungkol sa paggamit ng datos o code (halimbawa, kung ito ay isang eksperimental na bersyon o hindi angkop para sa produksyon).

Nakakaimpluwensya rin ang kaayusan sa pagiging madaling mabasa: ang pinakamahalagang impormasyon (ano ang proyekto, para saan ito, paano ito ginagamit) ang dapat unang lumitaw. sa simula ng dokumentonag-iiwan ng mga pangalawang detalye, pinahabang kredito, o mga tala sa kasaysayan para sa ibang pagkakataon. Sa ganitong paraan, ang isang taong nagba-browse pa lamang ay makakakuha ng malinaw na ideya sa isang mabilis na sulyap.

Karaniwang nilalaman ng isang README sa software

Sa mga proyekto ng software, ang mga README file ay kadalasang mas malalim pa ang nagagawa at may kasamang ilang karagdagang thematic blocks. Sa maraming pagkakataon, maikli lamang na ibinubuod ng file mga tagubilin sa pag-set up, mga tagubilin sa pag-install, mga pangunahing tagubilin sa paggamit, isang maghain ng manipesto (ipaliwanag kung para saan ang bawat mahalagang folder) at isang buod ng lisensya.

Karaniwan din na magsama ng isang seksyon na may impormasyon tungkol sa developer o team, mga posibleng paraan upang makapag-ambag sa proyekto, isang listahan ng mga kilalang error, at isang maikling gabay sa pag-troubleshoot para sa mga karaniwang problema. Ang lahat ng ito ay nakakatulong sa sinumang bumibisita sa repositoryo na magkaroon isang pandaigdigan at praktikal na pananaw nang hindi na kailangang maghanap sa ibang lugar.

Sa ilang mga kaso, ang README ay maaaring maglaman ng isang maliit na Palitan ang Log o tumuro sa isang panlabas na file na CHANGELOG. Karaniwan din na magsama ng seksyong "Balita" o "Ano'ng Bago" na nagtatampok ng mga kaugnay na pagbabago sa pagitan ng mga bersyon, lalo na kapag ang target na madla ay mga end user sa halip na mga developer.

Sa konteksto ng mga akademikong imbakan o datos, bilang karagdagan sa paglalarawan ng nilalaman, maraming template ang nagrerekomenda ng paglalarawan ang metodolohiya sa pagkolekta o pagbuo ng datos, ang mga baryabol na kasama, ang temporal at heograpikong saklaw ng impormasyon, at anumang kaugnay na limitasyon sa paggamit o interpretasyon.

Ang README bilang isang kasangkapan sa komunikasyon sa GitHub

Kapag nag-upload ka ng isang proyekto sa GitHub, ang README ay hindi lamang nagiging dokumentasyon, kundi isa ring... elemento ng komunikasyon at presentasyonSa katunayan, inirerekomenda mismo ng platform ang pagdaragdag ng README sa anumang pampublikong repositoryo upang matulungan ang mga bisita na mabilis na maunawaan kung tungkol saan ang proyekto.

Maaari mong gamitin ang README upang ipaliwanag kung ano ang ginagawa ng proyektoBakit ito maaaring maging kapaki-pakinabang, paano magsimula (halimbawa, gamit ang seksyong "Pagsisimula"), saan makakakuha ng tulong (mga isyu, forum, chat, atbp.), at kung sino ang aktibong nagpapanatili ng code. Ang lahat ng ito ay nakakaimpluwensya sa nakikitang kalidad at sa tiwala na nalilikha ng repository.

Sa maraming pagkakataon, ginagamit ng mga developer ang kanilang mga repositoryo ng GitHub bilang propesyonal na portfolioSa kontekstong ito, ang mga mahusay na ginawang README ay nakakagawa ng malaking pagkakaiba: pinapayagan nito ang mga recruiter o iba pang interesadong partido na makita, sa isang sulyap, ang saklaw ng proyekto, ang mga teknolohiyang ginamit, at ang mga pamamaraan ng paggawa ng may-akda.

Kung ang iyong intensyon ay hindi makaakit ng mga kontribusyon o i-promote ang repository (halimbawa, kung ito ay isang pribado o napaka-internal na proyekto), ang isang napakadetalyadong README ay hindi sapilitan. Gayunpaman, karaniwang praktikal na magpanatili ng kahit isa minimum na pangunahing dokumentasyon para sa personal at panggrupong gamit.

Nag-aalok din ang GitHub ng ilang partikular na kagamitan na may kaugnayan sa README: awtomatiko itong bumubuo ng index, sumusuporta sa mga badge at icon, at nagbibigay-daan sa iyong magpasok ng mga imahe, GIF, o video upang ipakita ang proyekto. Kung gagamitin nang epektibo, ang lahat ng mga elementong ito ay maaaring gawing mas epektibo ang README. mas kaakit-akit at mas madaling i-navigate.

Paano buuin at pahusayin ang iyong README

Kapag sinusuri ang mga sikat na repositoryo (halimbawa, mga proyekto mula sa malalaking organisasyon ng teknolohiya o mga ahensya sa kalawakan), napapansin na ang kanilang mga README file ay karaniwang nagbabahagi ng ilang karaniwang mga patternbagama't ang bawat proyekto ay nagpapanatili ng sarili nitong biswal at nilalamang pagkakakilanlan.

Karaniwang makahanap ng isang malinaw na pamagat at isang posibleng larawan sa pabalat (tulad ng logo o banner para sa proyekto), na sinusundan ng ilang badge na nagbubuod sa katayuan, lisensya, kasalukuyang bersyon, o katayuan sa pagsubok ng proyekto. Pagkatapos ay karaniwang mayroong paglalarawan ng proyekto, isang seksyon tungkol sa katayuan (matatag, nasa ilalim ng pagbuo, eksperimental, atbp.) at isang seksyon na may mga demonstrasyon o screenshot.

Karaniwan din na makahanap ng isang bloke na may pag-access sa proyekto (mga link sa na-deploy na bersyon, dokumentasyon, at mga nailathalang pakete), isang listahan ng mga teknolohiyang ginamit, mga seksyong nakalaan para sa mga kontribyutor, developer, at, siyempre, ang lisensyaAng mga elementong ito ay nakakatulong sa README na gumana bilang mabilis na gabay para sa mga gumagamit at bilang business card para sa mga potensyal na kontribyutor.

Tungkol sa disenyo, bagama't pinag-uusapan natin ang isang text file, maraming espasyo para gawin itong mas madaling basahin: gumamit ng maayos na istrukturang mga heading, mga listahang nakaayos at hindi nakaayos, mga talahanayan kung saan naaangkop, at Naka-bold na teksto para i-highlight ang mga pangunahing ideyaSa Markdown, maaari ka ring maglagay ng mga larawan, GIF, at maliliit na dekorasyon (tulad ng mga emoji) para mas madaling gamitin, at laging isaalang-alang ang kalinawan.

Isang hindi gaanong napag-uusapang paraan ay ang palaging pagsusulat habang iniisip ang isang taong Wala talaga siyang alam tungkol sa proyekto.Nangangahulugan ito ng pag-iwas sa mga pagpapalagay tungkol sa dating kaalaman, paggamit ng malinaw at direktang wika, at paglilinaw ng mga teknikal na termino sa unang pagkakataon na lumitaw ang mga ito. At, siyempre, pagpapanatiling updated ang README tuwing may mahalagang pagbabago sa proyekto.

Lisensya, mga kontribusyon at pagiging awtor

Sa mga proyektong open source, isang partikular na mahalagang seksyon ng README ay ang nakalaan para sa lisensyaAng paglalathala ng code sa isang pampublikong repositoryo ay hindi awtomatikong ginagawa itong malayang software; kinakailangang tahasang sabihin sa ilalim ng kung anong mga kondisyon ito maaaring ituring na malayang software. gagamitin, babaguhin, at ipamahagi muli.

Ang pinakakaraniwang gawain ay ang paggamit ng mga kilalang lisensya (MIT, Apache, GPL, Creative Commons para sa dokumentasyon, atbp.) at mag-link mula sa README file patungo sa LICENSE o COPYING file ng repository. Sa ganitong paraan, agad na malalaman ng sinumang interesado kung ano ang maaari nilang gawin sa code at kung ano ang kanilang mga obligasyon (halimbawa, attribution, share alike, mga limitasyon ng pananagutan, atbp.).

Ang isa pang mahalagang bloke sa isang mature na README ay ang gabay sa kontribusyonIpinapaliwanag ng seksyong ito kung paano maaaring mag-ambag ang iba sa proyekto: mga alituntunin sa istilo, ang proseso para sa pagsusumite ng mga pull request, kung paano mag-ulat ng mga bug, kung anong mga uri ng kontribusyon ang tinatanggap, at kung saan pinag-uugnay ang trabaho. Minsan ang impormasyong ito ay nakapaloob sa isang hiwalay na CONTRIBUTING.md file na naka-link mula sa README.

Mainam din na gawing malinaw ang mga indibidwal at developer na nag-aambagAng ilang proyekto ay may kasamang mga talahanayan na may mga avatar at pangalan na naka-link sa kanilang mga profile, habang ang iba ay naglilista lamang ng mga pangunahing gumagamit. Ang kilos na ito ay hindi lamang kumikilala sa trabaho kundi nagpapadali rin sa direktang pakikipag-ugnayan kung may kailangang makipag-usap sa isang partikular na miyembro ng koponan.

Panghuli, mahalagang maglaan ng ilang linya para ipaliwanag paano makakuha ng tulong At anong mga channel ang umiiral: mga isyu sa GitHub, mga forum, mga mailing list, mga chat, atbp. Kung ang proyekto ay hindi nag-aalok ng opisyal na suporta, balido rin na malinaw na ipahiwatig ito upang maiwasan ang mga hindi pagkakaunawaan.

Dahil sa lahat ng nabanggit, ang README file ay nagiging isang mahalagang bahagi ng anumang digital na proyekto: Ipinaliliwanag nito kung ano ito, paano ito gumagana, sino ang nagpapanatili nito, at sa ilalim ng anong mga kondisyon ito maaaring gamitin.Ang pag-aalaga at pagpapanatiling napapanahon ng iyong nilalaman ay isang maliit na pamumuhunan na malaki ang maitutulong sa kung paano nakikita at ginagamit ng ibang tao ang iyong trabaho.

Kaugnay na artikulo:

Paano sumulat ng kapaki-pakinabang at napapanatiling teknikal na dokumentasyon ng software

Isaac

Masigasig na manunulat tungkol sa mundo ng mga byte at teknolohiya sa pangkalahatan. Gustung-gusto kong ibahagi ang aking kaalaman sa pamamagitan ng pagsusulat, at iyon ang gagawin ko sa blog na ito, ipakita sa iyo ang lahat ng mga pinaka-kagiliw-giliw na bagay tungkol sa mga gadget, software, hardware, teknolohikal na uso, at higit pa. Ang layunin ko ay tulungan kang mag-navigate sa digital na mundo sa simple at nakakaaliw na paraan.