Kas ir README faili un kā tos pareizi lietot?

Ja strādājat ar digitālajiem projektiem, agrāk vai vēlāk jūs saskarsieties ar failu ar nosaukumu READMELai gan tas var šķist vienkāršs teksta dokuments, tas ir daudz svarīgāks, nekā šķiet: tas ir motivācijas vēstule jūsu projektam, pirmais sākumpunkts ikvienam, kurš vēlas uzzināt, ko esat paveicis, kā to izmantot un vai tas ir viņa laika vērts.

Programmatūras izstrādes, datu zinātnes vai pat akadēmiskā darba un sadarbības projektu pasaulē a LASĪTMAN labi uzrakstīts Tas ietaupa jūsu laiku, novērš kļūdas un atvieglo citiem (vai pat jums pašiem pēc dažiem mēnešiem) projekta mērķa ātru izpratni. Aplūkosim tuvāk, kas ir README faili, kam tie paredzēti, kas tajos jāiekļauj un kā no tiem gūt maksimālu labumu.

Kas īsti ir README fails?

README fails ir teksta dokuments, kas pievienots digitālajam projektam Tā galvenais mērķis ir skaidri izskaidrot projekta saturu, tā mērķi un lietošanas veidu. Burtiski tulkojot, tas būtu kaut kas līdzīgs "izlasi mani", un tieši tāda ir tā funkcija: būt pirmajai lietai, ko kāds izlasa, atverot repozitoriju, datu mapi vai programmatūras pakotni.

Šāda veida failus var saglabāt dažādos formātos teksta formātino klasikas README.txt (vienkāršs teksts) līdz readme.doc, readme.1st vai retāk sastopami paplašinājumi, piemēram, . MeKonkrētais formāts parasti tiek pielāgots operētājsistēma un programma, ar kuru tā tiks parādītalai jebkurš lietotājs varētu atvērt un lasīt failu bez jebkādām sarežģījumiem.

Mūsdienās, īpaši programmatūras projektos un koda krātuvēs, visizplatītākais formāts ir README.mdPaplašinājums .md norāda, ka fails ir ierakstīts MarkdownHTML ir ļoti vienkārša iezīmēšanas valoda, kas ļauj konvertēt tekstu HTML formātā, formatēšanai izmantojot tikai dažus simbolus. Tas atvieglo satura formatēšanu. viegli lasāms gan neapstrādātā, gan renderētā veidā tīmeklīpapildus tam, ka bez sarežģījumiem var izmantot nosaukumus, sarakstus, saites, tabulas, attēlus un citas lietas.

Labi strukturēts README fails piedāvā lietotājam vai līdzstrādniekam pilnīgs un saprotams projekta kopsavilkumsTas nav paredzēts kā izsmeļošs dokuments, bet gan kā praktisks ceļvedis: ko projekts dara, kāpēc tas ir noderīgs, kā sākt to izmantot un kur atrast vairāk informācijas, ja nepieciešams.

Datu jomā, piemēram, datu kopu krātuvēs, ļoti bieži README (dažreiz formātā) ir README.txt) savākt Vispārīga informācija, autorība, atslēgvārdi, ģeogrāfiskais un laika aptvērums, lietošanas licence un metodoloģija ko izmanto datu ģenerēšanai vai apkopošanai, kā arī Ieteicamā programmatūra darbam ar tiem.

Īsa README failu vēsture un standarta lietošana

Lai gan mūsdienās mēs tos galvenokārt saistām ar tādām platformām kā GitHub, prakse iekļaut README failu programmatūras pakotnēs nāk no pirms gadu desmitiemIr dokumentēti piemēri, kas datējami ar 20. gadsimta 70. gadu vidū, kad programmas jau tika izplatītas ar nelielu dokumentu, kurā bija paskaidrots to saturs un lietošana.

Laika gaitā šī prakse kļuva tik ļoti nostiprinājusies, ka GNU kodēšanas standarti (GNU kodēšanas standarti) README fails tiek uzskatīts par prasībaŠie standarti ievērojami ietekmēja brīvās programmatūras ekosistēmu un veicināja README faila kļūšanu par gandrīz obligātu jebkurā nopietnā programmatūras pakotnē.

Kad tīmeklis kļuva par standarta platforma programmatūras izplatīšanaiDaudzi projekti sāka pārvietot daļu informācijas, kas iepriekš bija README failā (rokasgrāmatas, licence, jaunumi utt.), uz tīmekļa vietnēm, wiki lapām vai pirmkoda tarball pakotnePat tā, README fails nekad nepazuda: daudzos gadījumos tas palika nemainīgs. lokāls kopsavilkumslai gan dažreiz tas palika nedaudz nepilnīgs, salīdzinot ar tiešsaistes dokumentāciju.

Tādu platformu popularitāte kā GitHub Un, pateicoties atzītāku brīvās programmatūras kopienu centieniem, README faili atkal ir nonākuši priekšplānā. Piemēram, GitHub, ja repozitorija saknes direktorijā ir README fails, sistēma to automātiski pievienos. Tas automātiski konvertē uz HTML un parāda to sākumlapā projekta, tāpēc tā ir pirmā lieta, ko redzat, ieejot.

Turklāt jēdziens “lasāmfails” dažreiz tiek lietots vispārējs Atsauce uz jebkuru īsu dokumentu, kas izskaidro mapes vai projekta saturu, pat ja faila nosaukums nav tieši README. Daudzi bezmaksas programmatūras projekti izplata standarta failu komplektu kopā ar README, katram no kuriem ir precīzi definēta funkcija.

Tipiski faili, kas tiek pievienoti README failam

Projektos, kas atbilst tādiem standartiem kā Gnits standarti vai tie, kas ģenerēti ar tādiem rīkiem kā GNU AutotoolsPapildus galvenajam README failam bieži var atrast arī citus teksta failus, kas papildina projekta informāciju. Daži no tipiskākajiem ir:

• README: vispārīga informācija par projektu, tā mērķi un kopējo redzējumu.
• AUTORI: galveno autoru vai līdzstrādnieku saraksts.
• PALDIES: pateicības cilvēkiem vai iestādēm, kas ir palīdzējušas.
• CHANGELOG: detalizēts izmaiņu žurnāls, kas galvenokārt paredzēts izstrādātājiem.
• JAUNUMI: kodolīgāks un saprotamāks izmaiņu žurnāls lietotājiem.
• INSTALL: īpašas uzstādīšanas instrukcijas un tehniskās prasības.
• KOPĒŠANA / LICENCE: programmatūras lietošanas un izplatīšanas licences teksts.
• BUGSZināmas kļūdas un veidi, kā par tām pareizi ziņot.
• FAQBieži uzdotie jautājumi un atbildes uz tiem.
• VISI: nepabeigto uzdevumu saraksts un plānotie turpmākie uzlabojumi.

Visi šie dokumenti kopā ar README veido pamatdokumentācijas skelets daudzu pakotņu. Dažos gadījumos daļa no šīs informācijas tiek dublēta gan repozitorijā, gan projekta tīmekļa vietnē, lai atvieglotu piekļuvi no dažādiem kanāliem.

README loma GitHub un līdzīgās platformās

GitHub platformā README failam ir īpaši svarīga loma. Pirmkārt, tas parasti ir pirmais, ko kāds ierauga kas apmeklē jūsu repozitorijsJa fails ir labi izstrādāts, dažu sekunžu laikā būs skaidrs, ko projekts dara, kāpēc tas varētu būt interesants, kā to palaist un kas aiz tā stāv.

GitHub automātiski atpazīst README failu, kad tas tiek ievietots noteiktās repozitorija vietās. Ja ievietojat to mapē .github, In saknes direktorija vai mapē docsplatforma to atpazīst un redzami izliek apmeklētājiem. Ja ir vairāki README faili, GitHub ievēro prioritārā secība: pirmā meklēšana .github, tad pie saknes un visbeidzot pie docs.

Turklāt, ja izveidojat publisku repozitoriju, kura nosaukums precīzi atbilst jūsu lietotājvārds Un, ja saknes direktorijam pievienojat README failu, šis fails automātiski kļūst par jūsu README failu. Profila READMETas tiek parādīts jūsu lietotāja lapā, ļaujot jums izveidot pielāgotu prezentācijas sadaļu, izmantojot GitHub Flavored Markdown.

Kad GitHub tiek skatīts README (vai jebkurš .md fails), platforma automātiski ģenerē Satura rādītājs pamatojoties uz dokumentu nosaukumiem. Šo indeksu var apskatīt, noklikšķinot uz ikonas "Struktūra", kas ievērojami atvieglo navigāciju garos README failos ar vairākām sadaļām.

GitHub arī ļauj tieši saite uz konkrētām sadaļāmKatrs virsraksts automātiski ģenerē enkuru; vienkārši virzot kursoru virs nosaukuma, tiks parādīta saites ikona. Tas ļauj kopīgot URL, kas tieši norāda uz konkrēto README sadaļu, kuru vēlaties izcelt (piemēram, instalācijas vai ieguldījumu sadaļu).

Ir viena svarīga praktiska detaļa: veiktspējas apsvērumu dēļ, ja jūsu README pārsniedz 500 KiB izmēra, GitHub saīsinās saturu Sākot no šī brīža atveidotajā skatā, ieteicams failā README saglabāt tikai būtisku informāciju, bet garus pamācību materiālus vai rokasgrāmatas pārvietot uz wiki lapām vai atsevišķu dokumentāciju.

Formāts un saites README failā

Lai README failu būtu viegli uzturēt un tas labi darbotos gan GitHub, gan lokālajos klonos, ieteicams izmantot relatīvās saites un attēlu ceļus attiecībā pret failu, kurā tie atrodas. Piemēram, ja saknes direktorijā ir README fails un dokuments docs/CONTRIBUTING.mdSaite README failā izskatītos apmēram šādi: (docs/CONTRIBUTING.md).

Šāda veida relatīvā saite nozīmē, ka, pārslēdzot filiāles vai klonējot repozitoriju, maršruti turpina darboties pareizi bez nepieciešamības tos modificēt. GitHub iekšēji pārveido šos ceļus, lai norādītu uz pareizo faila versiju, pamatojoties uz parādīto atzaru. Ceļi, kas sākas ar /kas tiek interpretēti attiecībā pret repozitorija sakni, kā arī tādi izplatīti operatori kā ./ o ../.

Ir svarīgi, lai saites teksts Saglabājiet saiti vienā rindā, jo tās sadalīšana vairākās rindās var izraisīt tās darbības traucējumus. Turklāt izvairieties no absolūtām saitēm uz iekšējiem repozitorija failiem, jo ​​tās var nedarboties, ja mainās bāzes URL vai tiek izveidots atzarojums.

Attiecībā uz dokumenta darbības jomu ir vērts atcerēties, ka README failā jāiekļauj tikai svarīgākā informācija, lai sāktu lietot un sniegtu ieguldījumu projektam. Plašai dokumentācijai (lietotāja rokasgrāmatām, pilnīgām API rokasgrāmatām utt.) ir tīrāk izmantot Wiki vai atsevišķu dokumentācijas sistēmu, saistot to ar pašu README failu.

Kāds ir README faila faktiskais mērķis?

Papildus teorijai, README fails praksē darbojas kā sākotnējais ceļvedis un atskaites punktsTas nav paredzēts, lai aizstātu plašu formālu dokumentāciju, bet gan lai sniegtu strukturētu un praktisku skaidrojumu par projekta svarīgākajiem aspektiem.

Starp tā visizplatītākajiem lietojumiem ir: izskaidrojiet mērķi projekta ietvaros aprakstiet tajā iekļautos datus vai failus, norādiet, kā sākt to lietot, un norādiet galvenās tehniskās prasības un izvairīties no kļūdām, ko rada nepareiza lietošanaKad vairāki lietotāji strādā ar vienu un to pašu kodu vai datiem, skaidra README fails ietaupa neskaitāmus atkārtotus jautājumus.

Koplietotos projektos, īpaši lielās komandās vai atvērtā pirmkoda kopienās, README ir gandrīz komunikācijas infrastruktūras komponentsTas kalpo, lai saskaņotu cerības, norādītu projekta brieduma līmeni, definētu, kā ieguldījums tiek sniegts, un precizētu, kāds atbalsts tiek piedāvāts (ja tāds ir).

Pat personiskos projektos, pat ja pie tiem strādāsiet tikai jūs, labi uzrakstīts README fails kalpo kā ilgtermiņa atmiņaLaika gaitā ir viegli aizmirst lēmumus, atkarības vai instalēšanas soļus; to dokumentēšana pasargā jūs no nepieciešamības "no jauna atklāt" savu projektu mēnešus vēlāk.

Tāpēc README nav tikai formalitāte: tas ir praktisks rīks, kas uzlabo organizētība, komunikācija un uzturēšanas spēja jebkura veida digitālajam projektam.

Kad ir lietderīgi izveidot README failu?

Īsā atbilde ir tāda, ka ieteicams izveidot README failu. ikreiz, kad ir projekts, kas tiks izmantots, pārskatīts vai uzturēts kāds cits, nevis sākotnējais veidotājs… un tas attiecas arī uz jūsu nākotnes “es”. Tam nav jābūt milzīgam atvērtā pirmkoda repozitorijam: tam vienkārši jābūt zināmai sarežģītībai vai saturam, kas rada jautājumus.

Daži piemēri, kur README fails ir īpaši noderīgs, ir šādi: tīmekļa vai programmēšanas projektikur ieteicams izskaidrot prasības, izstrādes procesus, startēšanas komandas un izpildlaika vidi. Tas ir arī ļoti interesanti mapes ar svarīgiem datiemlai precizētu, ko šie dati pārstāv, to izcelsmi un iespējamos ierobežojumus.

Citi tipiski konteksti ir tīmekļa vietnes, kas mitinātas mitināšanas vietnēkas bieži ietver README failu ar izvietošanas instrukcijām vai akadēmiskie un tehniskie darbi, kurā README fails var aprakstīt skriptus, eksperimentus, izmantoto rīku versijas vai to, kā reproducēt rezultātus.

En sadarbības projektiNeatkarīgi no tā, vai tas ir iekšējs vai publisks, README ir gandrīz obligāts. Tas palīdz jauniem cilvēkiem vienmērīgāk pievienoties projektam un kalpo kā kopīga atsauce, lai uzturētu konsekventus lietošanas un ieguldījuma standartus starp visām ieinteresētajām personām.

Kādai informācijai jābūt iekļautai labā README failā?

Efektīvam README failam nav jābūt garam, taču tam ir jābūt labi organizēts un ļoti skaidrsIr iekļauta pamatinformācija, kas gandrīz vienmēr jāiekļauj, un cits papildu saturs, kas sniedz lielu pievienoto vērtību atkarībā no projekta veida.

Vismaz lielākā daļa labi dokumentētu repozitoriju un pakotņu ietver projekta nosaukums, Viena īss mērķa aprakstsrepozitorija satura kopsavilkums, Norādījumi par tā lietošanu vai uzstādīšanu un pamatprasības (atkarības, minimālā valodas versija, operētājsistēma utt.).

Ir arī ļoti ieteicams pievienot dažus saziņas vai atbalsta metodePat ja tas ir tikai e-pasts vai saite uz repozitorija sadaļu “Problēmas”, tas palīdz ikvienam, kurš saskaras ar problēmām, uzzināt, kur un kā par tām ziņot, nevis atstāt viņu apmaldījušos un neziņā, ar ko sazināties.

Papildus pamatinformācijai bieži vien ir noderīgi iekļaut informāciju par izveides datums vai versija pašreizējais, autoru vai atbildīgo personu saraksts, lietošanas licence un visus attiecīgos paziņojumus par datu vai koda izmantošanu (piemēram, ja tā ir eksperimentāla versija vai nav piemērota ražošanai).

Kārtība ietekmē arī lasāmību: vispirms jāparādās vissvarīgākajai informācijai (kas ir projekts, kam tas paredzēts, kā tas tiek izmantots). dokumenta sākumāatstājot sekundāras detaļas, plašākus titrus vai vēsturiskas piezīmes vēlākam laikam. Tādā veidā kāds, kurš vienkārši pārlūko saturu, var ātri uzmest tam skaidru priekšstatu.

Tipisks README faila saturs programmatūrā

Programmatūras projektos README faili bieži iet soli tālāk un ietver vairākus papildu tematiskos blokus. Daudzos gadījumos fails īsi apkopo iestatīšanas instrukcijas, uzstādīšanas instrukcijas, pamata lietošanas instrukcijas, a failu manifests (paskaidrojiet, kam paredzēta katra svarīgā mape) un licences kopsavilkumu.

Ir arī ierasts iekļaut sadaļu ar informācija par izstrādātāju vai komandu, iespējamos veidus, kā sniegt ieguldījumu projektā, zināmo kļūdu sarakstu un īsu problēmu novēršanas rokasgrāmatu bieži sastopamām problēmām. Tas viss palīdz ikvienam, kas apmeklē repozitoriju, globāls un praktisks redzējums bez nepieciešamības meklēt citur.

Dažos gadījumos README failā var būt neliels Mainīt žurnālu vai norādīt uz ārēju CHANGELOG failu. Ir arī diezgan bieži iekļaut sadaļu “Jaunumi” vai “Kas jauns”, kurā izceltas būtiskas izmaiņas starp versijām, īpaši, ja mērķauditorija ir gala lietotāji, nevis izstrādātāji.

Akadēmisko vai datu krātuvju kontekstā papildus satura aprakstam daudzas veidnes iesaka aprakstīt datu vākšanas vai ģenerēšanas metodoloģija, iekļautie mainīgie lielumi, informācijas laika un ģeogrāfiskais diapazons un visi attiecīgie lietošanas vai interpretācijas ierobežojumi.

README kā saziņas rīks vietnē GitHub

Augšupielādējot projektu vietnē GitHub, README fails kļūst ne tikai par dokumentāciju, bet arī par komunikācijas un prezentācijas elementsFaktiski pati platforma iesaka jebkurai publiskai krātuvei pievienot README failu, lai apmeklētāji varētu ātri saprast, par ko ir projekts.

Jūs varat izmantot README failu, lai paskaidrotu ko projekts daraKāpēc tas varētu būt noderīgi, kā sākt darbu (piemēram, ar sadaļu “Darba sākšana”), kur saņemt palīdzību (problēmu risināšanā, forumos, tērzēšanā utt.) un kas aktīvi uztur kodu. Tas viss ietekmē uztverto kvalitāti un repozitorija radīto uzticību.

Daudzos gadījumos izstrādātāji izmanto savas GitHub krātuves kā profesionālais portfelisŠajā kontekstā labi izstrādātiem README failiem ir milzīga nozīme: tie ļauj vervētājiem vai citām ieinteresētajām personām uzreiz redzēt projekta apjomu, izmantotās tehnoloģijas un autora darba metodes.

Ja jūsu mērķis nav piesaistīt ieguldījumus vai reklamēt repozitoriju (piemēram, ja tas ir privāts vai ļoti iekšējs projekts), ļoti detalizēts README fails nav obligāts. Pat tad parasti ir praktiski uzturēt vismaz vienu minimālā pamatdokumentācija personīgai un komandas lietošanai.

GitHub piedāvā arī dažas īpašas utilītas, kas saistītas ar README: tas automātiski ģenerē indeksu, atbalsta nozīmītes un ikonas, kā arī ļauj ievietot attēlus, GIF failus vai videoklipus, lai demonstrētu projektu. Pareizi izmantoti, visi šie elementi var padarīt README efektīvāku. pievilcīgāka un vieglāk orientējama.

Kā strukturēt un uzlabot savu README failu

Analizējot populāras krātuves (piemēram, lielu tehnoloģiju organizāciju vai kosmosa aģentūru projektus), tiek novērots, ka to README failos parasti ir vairākas kopīgas izplatīti modeļilai gan katrs projekts saglabā savu vizuālo un saturisko identitāti.

Ir ierasts atrast skaidrs nosaukums un, iespējams, vāka attēls (piemēram, projekta logotips vai baneris), kam seko dažas emblēmas, kas apkopo projekta statusu, licenci, pašreizējo versiju vai testēšanas statusu. Pēc tam parasti ir projekta apraksts, sadaļa par statusu (stabils, izstrādes stadijā, eksperimentāls utt.) un sadaļa ar demonstrācijām vai ekrānuzņēmumiem.

Ir arī ļoti bieži atrast bloku ar piekļuve projektam (saites uz izvietoto versiju, dokumentāciju un publicētajām pakotnēm), izmantoto tehnoloģiju saraksts, sadaļas, kas veltītas līdzstrādniekiem, izstrādātājiem un, protams, licenceŠie elementi palīdz README failam darboties gan kā ātrai rokasgrāmatai lietotājiem, gan kā vizītkartei potenciālajiem līdzstrādniekiem.

Runājot par dizainu, lai gan mēs runājam par teksta failu, ir daudz iespēju to padarīt vieglāk lasāmu: izmantojiet labi strukturētus virsrakstus, sakārtotus un nesakārtotus sarakstus, tabulas, kur tas ir piemēroti, un Treknrakstā izceltas galvenās idejasMarkdown var ievietot arī attēlus, GIF failus un mazus rotājumus (piemēram, emocijzīmes), lai padarītu to lietotājam draudzīgāku, vienmēr paturot prātā skaidrību.

Maz apspriests triks ir vienmēr rakstīt, domājot par kādu, kurš Viņš par projektu pilnīgi neko nezina.Tas nozīmē izvairīties no pieņēmumiem par iepriekšējām zināšanām, lietot skaidru un tiešu valodu un precizēt tehniskos terminus, tiklīdz tie parādās pirmo reizi. Un, protams, atjaunināt README failu ikreiz, kad projektā notiek būtiskas izmaiņas.

Licence, ieguldījums un autorība

Atvērtā pirmkoda projektos īpaši svarīga README sadaļa ir veltīta licenceKoda publicēšana publiskā repozitorijā automātiski nepadara to par brīvu programmatūru; ir nepieciešams skaidri norādīt, kādos apstākļos to var uzskatīt par brīvu programmatūru. lietošanai, modificēšanai un izplatīšanai.

Visizplatītākā prakse ir izmantot labi zināmas licences (MIT, Apache, GPL, Creative Commons dokumentācijai utt.) un izveidot saiti no README faila uz repozitorija LICENSE vai COPYING failu. Tādā veidā ikviens interesents nekavējoties zina, ko viņš var darīt ar kodu un kādas ir viņa saistības (piemēram, atsauce, koplietošana līdzīgā veidā, atbildības ierobežojumi utt.).

Vēl viens svarīgs bloks nobriedušā README failā ir ieguldījumu ceļvedisŠajā sadaļā ir paskaidrots, kā citi var dot savu ieguldījumu projektā: stila vadlīnijas, pieprasījumu iesniegšanas process, kļūdu ziņošana, pieņemto ieguldījumu veidi un darba koordinācijas vietas. Dažreiz šī informācija ir iekļauta atsevišķā CONTRIBUTING.md failā, uz kuru ir saite no README faila.

Tāpat ir ieteicams padarīt redzamu veicinoši indivīdi un izstrādātājiDažos projektos ir iekļautas tabulas ar avatāriem un vārdiem, kas saistīti ar viņu profiliem, savukārt citos vienkārši ir uzskaitīti galvenie lietotāji. Šī žesta veidā ne tikai tiek atzīts darbs, bet arī tiek atvieglota tieša saziņa, ja kādam ir nepieciešams runāt ar konkrētu komandas locekli.

Visbeidzot, ir vērts veltīt dažas rindiņas skaidrojumam kā saņemt palīdzību Un kādi kanāli pastāv: GitHub problēmas, forumi, adresātu saraksti, tērzēšana utt. Ja projekts nepiedāvā oficiālu atbalstu, ir arī pareizi to skaidri norādīt, lai izvairītos no pārpratumiem.

Ņemot vērā visu iepriekš minēto, README fails kļūst par jebkura digitālā projekta centrālo daļu: Tajā ir paskaidrots, kas tas ir, kā tas darbojas, kas to uztur un kādos apstākļos to var lietot.Rūpes par savu saturu un tā atjaunināšana ir neliels ieguldījums, kas būtiski ietekmē to, kā citi cilvēki uztver un izmanto jūsu darbu.