Kas yra README failai ir kaip juos tinkamai naudoti

Jei dirbate su skaitmeniniais projektais, anksčiau ar vėliau susidursite su failu, vadinamu SKAITYK MANENors tai gali atrodyti kaip paprastas tekstinis dokumentas, jis yra daug svarbesnis nei atrodo: tai yra motyvacinis laiškas jūsų projektui, pirmasis įėjimo taškas visiems, norintiems sužinoti, ką padarėte, kaip tuo naudotis ir ar verta tam skirti laiko.

Programinės įrangos kūrimo, duomenų mokslo ar net akademinio darbo ir bendradarbiavimo projektų pasaulyje a SKAITYKITE gerai parašyta Tai taupo jūsų laiką, apsaugo nuo klaidų ir leidžia kitiems (ar net jums patiems po kelių mėnesių) greičiau suprasti projekto tikslą. Panagrinėkime atidžiau, kas yra README failai, kam jie skirti, ką jie turėtų įtraukti ir kaip juos išnaudoti kuo geriau.

Kas tiksliai yra README failas?

README failas yra tekstinis dokumentas, pridedamas prie skaitmeninio projekto Pagrindinis jo tikslas – aiškiai paaiškinti, ką projektas apima, kam jis skirtas ir kaip jį naudoti. Pažodžiui išvertus tai būtų kažkas panašaus į „perskaityk mane“, ir būtent tokia ir yra jo funkcija: būti pirmuoju dalyku, kurį kas nors perskaito atidaręs saugyklą, duomenų aplanką ar programinės įrangos paketą.

Šio tipo failus galima išsaugoti skirtingose ​​vietose teksto formatai: iš klasikos readme.txt (paprastas tekstas) iki readme.doc, readme.1st arba retesni plėtiniai, pvz. . ManeKonkretus formatas paprastai pritaikomas prie operacinė sistema ir programa, su kuria ji bus rodomakad bet kuris vartotojas galėtų atidaryti ir perskaityti failą be jokių komplikacijų.

Šiandien, ypač programinės įrangos projektuose ir kodų saugyklose, labiausiai paplitęs formatas yra README.md.md plėtinys rodo, kad failas parašytas Akcijos kainosHTML yra labai paprasta žymėjimo kalba, leidžianti konvertuoti tekstą į HTML, naudojant vos kelis formatavimo simbolius. Tai palengvina turinio formatavimą. lengvai skaitoma tiek neapdorota, tiek atvaizduota forma internetebe to, leidžia be jokių komplikacijų naudoti pavadinimus, sąrašus, nuorodas, lenteles, vaizdus ir dar daugiau.

Gerai struktūrizuotas README failas vartotojui arba bendraautoriui suteikia išsami ir suprantama projekto santraukaTai nėra išsamus dokumentas, o praktinis vadovas: ką projektas daro, kodėl jis naudingas, kaip jį pradėti naudoti ir kur prireikus rasti daugiau informacijos.

Duomenų srityje, pavyzdžiui, duomenų rinkinių saugyklose, labai dažnai README (kartais formatu) yra readme.txt) rinkti Bendra informacija, autorystė, raktažodžiai, geografinė ir laiko aprėptis, naudojimo licencija ir metodologija naudojami duomenims generuoti arba rinkti, taip pat Rekomenduojama programinė įranga darbui su jais.

Trumpa README failų istorija ir standartinis naudojimas

Nors šiandien juos dažniausiai siejame su tokiomis platformomis kaip „GitHub“, README failo įtraukimo į programinės įrangos paketus praktika kilo iš prieš dešimtmečiusYra dokumentuotų pavyzdžių, datuojamų aštuntojo dešimtmečio viduryje, kai programos jau buvo platinamos su nedideliu dokumentu, kuriame paaiškintas jų turinys ir naudojimas.

Laikui bėgant ši praktika taip įsigalėjo, kad 2013 m. GNU kodavimo standartai (GNU kodavimo standartai) README failas laikomas reikalavimasŠie standartai padarė didelę įtaką laisvosios programinės įrangos ekosistemai ir prisidėjo prie to, kad README failas tapo beveik privalomas bet kuriame rimtame programinės įrangos pakete.

Kai internetas tapo standartinė programinės įrangos platinimo platformaDaugelyje projektų dalis informacijos, kuri anksčiau buvo README faile (vadovai, licencija, naujienos ir kt.), buvo perkelta į svetaines, vikius arba šaltinio kodo tarball paketasNepaisant to, README failas niekada nedingo: daugeliu atvejų jis liko toks pat vietinė santraukanors kartais, palyginti su internetine dokumentacija, ji liko šiek tiek nepilna.

Tokių platformų kaip populiarumas GitHub O labiau įsitvirtinusių laisvosios programinės įrangos bendruomenių pastangos vėl iškėlė README failus į pirmą planą. Pavyzdžiui, „GitHub“ saugykloje, jei šakniniame kataloge yra README failas, sistema jį automatiškai pridės. Jis automatiškai konvertuojamas į HTML ir rodomas pagrindiniame puslapyje projekto, todėl tai pirmas dalykas, kurį matote įėję.

Be to, kartais vartojama „readme failo“ sąvoka. bendrinis Nurodyti bet kokį trumpą dokumentą, kuriame paaiškinamas aplanko ar projekto turinys, net jei failas nėra tiksliai pavadintas README. Daugelis nemokamos programinės įrangos projektų platina standartinį failų rinkinį kartu su README, kurių kiekvienas turi aiškiai apibrėžtą funkciją.

Tipiniai failai, pridedami prie README failo

Projektuose, kurie atitinka tokius standartus kaip Gnits standartai arba sugeneruoti naudojant tokius įrankius kaip GNU AutotoolsBe pagrindinio README failo, įprasta rasti ir kitų tekstinių failų, kurie papildo projekto informaciją. Kai kurie tipiškiausi yra šie:

• SKAITYK MANE: bendra informacija apie projektą, jo tikslą ir bendrą viziją.
• AUTORIAIpagrindinių autorių arba bendradarbių sąrašas.
• AČIŪ: padėkos žmonėms ar institucijoms, kurios padėjo.
• CHANGELOGAS: išsamus pakeitimų žurnalas, skirtas pirmiausia kūrėjams.
• NAUJIENOS: glaustesnis ir suprantamesnis pakeitimų žurnalas galutiniams vartotojams.
• INSTALL: konkrečios įrengimo instrukcijos ir techniniai reikalavimai.
• KOPIJAVIMAS / LICENCIJA: programinės įrangos naudojimo ir platinimo licencijos tekstas.
• KLAIDASŽinomos klaidos ir būdai, kaip jas teisingai pranešti.
• FAQDažnai užduodami klausimai ir į juos atsakymai.
• VISI: laukiamų užduočių ir planuojamų būsimų patobulinimų sąrašas.

Visi šie dokumentai kartu su README sudaro pagrindinės dokumentacijos skeletas daugelio paketų. Kai kuriais atvejais dalis šios informacijos yra dubliuojama tiek saugykloje, tiek projekto svetainėje, kad būtų lengviau prieiti prie jos iš skirtingų kanalų.

README vaidmuo „GitHub“ ir panašiose platformose

„GitHub“ platformoje README failas vaidina ypač svarbų vaidmenį. Visų pirma, jis paprastai yra pirmas dalykas, kurį kas nors pamato kuris apsilanko jūsų saugyklaJei failas bus gerai parengtas, per kelias sekundes bus aišku, ką projektas daro, kodėl jis gali būti įdomus, kaip jį paleisti ir kas už jo stovi.

„GitHub“ automatiškai atpažįsta README failą, kai jis patalpinamas tam tikrose saugyklos vietose. Jei patalpinsite jį aplanke .githubBe šakninis katalogas arba aplanke docsplatforma tai aptinka ir aiškiai matomoje vietoje lankytojams. Kai yra keli README failai, „GitHub“ vadovaujasi prioritetų tvarka: pirmoji paieška .github, tada prie šaknies ir galiausiai prie docs.

Be to, jei sukursite viešąją saugyklą, kurios pavadinimas tiksliai sutampa su jūsų vartotojo vardas O jei į šakninį katalogą įdėsite README failą, tas failas automatiškai taps jūsų README failu. Profilis READMEJis rodomas jūsų vartotojo puslapyje, todėl galite sukurti pasirinktinį pristatymo skyrių naudodami „GitHub Flavored Markdown“.

Kai „GitHub“ platformoje peržiūrimas README (arba bet kuris .md failas), platforma automatiškai sugeneruoja Turinys remiantis dokumentų pavadinimais. Šią rodyklę galite peržiūrėti spustelėdami piktogramą „Struktūra“, kuri labai palengvina naršymą ilguose README failuose su keliais skyriais.

„GitHub“ taip pat leidžia tiesiogiai susieti su konkrečiais skyriaisKiekviena antraštė automatiškai sukuria inkarą; tiesiog užvedus pelės žymeklį ant pavadinimo, bus parodyta nuorodos piktograma. Tai leidžia bendrinti URL adresus, kurie tiesiogiai nukreipia į konkrečią README skiltį, kurią norite paryškinti (pavyzdžiui, diegimo arba įnašų skiltį).

Yra viena svarbi praktinė detalė: dėl našumo priežasčių, jei jūsų README viršija 500 KiB dydžio, „GitHub“ sutrumpins turinį Nuo to taško pateikiamame vaizde. Todėl rekomenduojama README failą skirti tik svarbiausiai informacijai, o ilgus vadovėlius ar vadovus perkelti į wiki puslapius arba atskirą dokumentaciją.

Formatas ir nuorodos README faile

Kad README būtų lengva prižiūrėti ir gerai veiktų tiek „GitHub“, tiek vietiniuose klonuose, rekomenduojama naudoti santykinės nuorodos ir paveikslėlių kelius, susijusius su failu, kuriame jie yra. Pavyzdžiui, jei šakniniame kataloge yra README failas, o dokumentas docs/CONTRIBUTING.mdNuoroda README faile atrodytų maždaug taip: (docs/CONTRIBUTING.md).

Šis santykinio ryšio tipas reiškia, kad keičiant šakas arba klonuojant saugyklą, maršrutai ir toliau veikia tinkamai nereikalaujant jų modifikuoti. „GitHub“ šiuos kelius transformuoja taip, kad jie nukreiptų į teisingą failo versiją pagal rodomą šaką. Keliai, prasidedantys /kurie interpretuojami atsižvelgiant į saugyklos šaknį, taip pat įprastus operatorius, tokius kaip ./ o ../.

Svarbu, kad nuorodos tekstas Nuorodą palikite vienoje eilutėje, nes jos padalijimas į kelias eilutes gali sukelti gedimus. Be to, venkite absoliučių nuorodų į vidinius saugyklos failus, nes jos gali nutrūkti, jei pasikeičia bazinis URL arba sukuriama atšaka.

Kalbant apie dokumento apimtį, verta prisiminti, kad README faile turėtų būti tik esminė informacija, norint pradėti naudoti ir prisidėti projektui. Išsamiai dokumentacijai (naudotojo vadovams, išsamiems API vadovams ir kt.) yra švariau naudoti wiki arba atskirą dokumentacijos sistemą, susiejant ją su pačiu README failu.

Kokia yra tikroji README failo paskirtis?

Be teorijos, README failas praktiškai veikia kaip pradinis vadovas ir atskaitos taškasJis nėra skirtas pakeisti išsamią oficialią dokumentaciją, o veikiau pateikti tvarkingą ir praktišką svarbiausių projekto aspektų paaiškinimą.

Tarp dažniausiai naudojamų jo naudojimo būdų yra: paaiškinkite tikslą projekto aprašymą, aprašykite, kokius duomenis ar failus jis apima, nurodykite, kaip pradėti jį naudoti, ir nurodykite pagrindinius techninius reikalavimus ir išvengti klaidų, atsiradusių dėl netinkamo naudojimoKai su tuo pačiu kodu ar duomenimis dirba keli vartotojai, aiški README byla padeda išvengti begalės pasikartojančių klausimų.

Bendruose projektuose, ypač didelėse komandose ar atvirojo kodo bendruomenėse, README yra beveik ryšių infrastruktūros komponentasTai padeda suderinti lūkesčius, nurodyti projekto brandos lygį, apibrėžti, kaip prisidedama, ir paaiškinti, kokia parama siūloma (jei tokia siūloma).

Net ir asmeniniuose projektuose, net jei prie jų dirbsite tik jūs, gerai parašytas README failas veikia kaip ilgalaikė atmintisLaikui bėgant, lengva pamiršti sprendimus, priklausomybes ar diegimo veiksmus; jų dokumentavimas apsaugo jus nuo to, kad po kelių mėnesių iš naujo nereikėtų „atrasti“ savo projekto.

Todėl README nėra tik formalumas: tai praktiška priemonė, kuri pagerina organizuotumas, bendravimas ir priežiūra bet kokio tipo skaitmeninio projekto.

Kada tikslinga kurti README failą?

Trumpai tariant, patartina sukurti README failą. kai tik bus projektas, kuris bus naudojamas, peržiūrimas ar prižiūrimas kažkas kitas, o ne originalus kūrėjas... ir tai apima ir jūsų ateities „aš“. Tai nebūtinai turi būti didžiulė atvirojo kodo saugykla: ji tiesiog turi būti tam tikro sudėtingumo arba turinys turi kelti klausimų.

Kai kurie pavyzdžiai, kur README failas yra ypač naudingas, yra šie: žiniatinklio ar programavimo projektaikur patartina paaiškinti reikalavimus, kūrimo procesus, paleidimo komandas ir vykdymo aplinką. Tai taip pat labai įdomu aplankai su svarbiais duomenimisišsiaiškinti, ką tie duomenys reiškia, jų kilmę ir galimus apribojimus.

Kiti tipiški kontekstai yra svetainės, talpinamos talpinimo platformojekurie dažnai apima README failą su diegimo instrukcijomis arba akademiniai ir techniniai darbai, kuriame README gali aprašyti scenarijus, eksperimentus, naudotų įrankių versijas arba kaip atkurti rezultatus.

En bendradarbiavimo projektaiNesvarbu, ar tai vidinis, ar viešas projektas, README yra beveik privalomas. Jis padeda naujiems žmonėms sklandžiau prisijungti prie projekto ir veikia kaip bendra nuoroda, padedanti palaikyti nuoseklius naudojimo ir indėlio standartus tarp visų suinteresuotųjų šalių.

Kokia informacija turėtų būti gerame README faile?

Efektyvus README failas nebūtinai turi būti ilgas, bet jis turi būti gerai organizuota ir labai aiškiYra tam tikra pagrindinė informacija, kuri beveik visada turėtų būti įtraukta, ir kitas neprivalomas turinys, kuris suteikia daug vertės, priklausomai nuo projekto tipo.

Bent jau daugumoje gerai dokumentuotų saugyklų ir paketų yra projekto pavadinimas, Vienas trumpas tikslo aprašymassaugyklos turinio santrauka, Naudojimo ar diegimo instrukcijos ir esminius reikalavimus (priklausomybes, minimalią kalbos versiją, operacinę sistemą ir kt.).

Taip pat labai rekomenduojama pridėti šiek tiek susisiekimo arba palaikymo būdasNet jei tai tik el. laiškas ar nuoroda į saugyklos skyrių „Problemos“, tai padės visiems, susidūrusiems su problemomis, kur ir kaip apie jas pranešti, o ne palikti juos pasimetusius ir nežinančius, su kuo susisiekti.

Be pagrindinių dalykų, dažnai naudinga įtraukti informaciją apie sukūrimo data arba versija dabartinis, autorių arba atsakingų šalių sąrašas, naudojimo licencija ir visus susijusius pranešimus apie duomenų ar kodo naudojimą (pavyzdžiui, jei tai eksperimentinė versija arba netinka gamybai).

Tvarka taip pat turi įtakos skaitomumui: svarbiausia informacija (kas yra projektas, kam jis skirtas, kaip jis naudojamas) turėtų būti pateikta pirmiausia. dokumento pradžiojepaliekant antrines detales, išplėstinius titrus ar istorines pastabas vėlesniam laikui. Tokiu būdu, kas nors, kas tik naršo, gali susidaryti aiškų vaizdą vos žvilgtelėjęs.

Tipinis README turinys programinėje įrangoje

Programinės įrangos projektuose README failai dažnai žengia dar vieną žingsnį ir apima kelis papildomus teminius blokus. Daugeliu atvejų failas trumpai apibendrina sąrankos instrukcijas, įrengimo instrukcijos, pagrindinės naudojimo instrukcijos, failo manifestas (paaiškinkite, kam skirtas kiekvienas svarbus aplankas) ir licencijos santrauką.

Taip pat įprasta įtraukti skyrių su informacija apie kūrėją arba komandą, galimus būdus prisidėti prie projekto, žinomų klaidų sąrašą ir trumpą dažniausiai pasitaikančių problemų šalinimo vadovą. Visa tai padeda kiekvienam, apsilankiusiam saugykloje, globali ir praktiška vizija nereikalaujant ieškoti kitur.

Kai kuriais atvejais README faile gali būti nedidelis Pakeisti žurnalą arba nukreipti į išorinį CHANGELOG failą. Taip pat gana įprasta įtraukti skyrių „Naujienos“ arba „Kas naujo“, kuriame pabrėžiami svarbūs versijų pakeitimai, ypač kai tikslinė auditorija yra galutiniai vartotojai, o ne kūrėjai.

Akademinių ar duomenų saugyklų kontekste, be turinio aprašymo, daugelyje šablonų rekomenduojama aprašyti duomenų rinkimo arba generavimo metodika, įtrauktus kintamuosius, informacijos laiko ir geografinį aprėptį ir visus svarbius naudojimo ar interpretavimo apribojimus.

README kaip komunikacijos įrankis „GitHub“ platformoje

Kai įkeliate projektą į „GitHub“, README tampa ne tik dokumentacija, bet ir komunikacijos ir pristatymo elementasIš tiesų, pati platforma rekomenduoja į bet kurią viešąją saugyklą įtraukti README failą, kad lankytojai galėtų greitai suprasti, apie ką yra projektas.

Galite naudoti README, kad paaiškintumėte ką daro projektasKodėl tai gali būti naudinga, kaip pradėti (pavyzdžiui, su skyriumi „Darbo pradžia“), kur gauti pagalbos (problemos, forumai, pokalbiai ir kt.) ir kas aktyviai prižiūri kodą. Visa tai daro įtaką suvokiamai kokybei ir saugyklos kuriamam pasitikėjimui.

Daugeliu atvejų kūrėjai naudoja savo „GitHub“ saugyklas kaip profesionalus portfelisŠiame kontekste gerai parengti README failai daro didžiulį skirtumą: jie leidžia įdarbintojams ar kitoms suinteresuotoms šalims iš pirmo žvilgsnio pamatyti projekto apimtį, naudojamas technologijas ir autoriaus darbo metodus.

Jei nesiekiate pritraukti naujų narių ar reklamuoti saugyklos (pavyzdžiui, jei tai privatus arba labai vidinis projektas), labai išsamus README failas nėra privalomas. Net ir tokiu atveju paprastai praktiška turėti bent vieną minimali pagrindinė dokumentacija asmeniniam ir komandos naudojimui.

„GitHub“ taip pat siūlo keletą specifinių su README susijusių paslaugų: ji automatiškai generuoja indeksą, palaiko ženklelius ir piktogramas bei leidžia įterpti vaizdus, ​​GIF ar vaizdo įrašus projektui pristatyti. Veiksmingai naudojami visi šie elementai gali padaryti README veiksmingesnį. patrauklesnis ir lengviau naršomas.

Kaip struktūrizuoti ir patobulinti savo README failą

Analizuojant populiarias saugyklas (pavyzdžiui, didelių technologijų organizacijų ar kosmoso agentūrų projektus), pastebima, kad jų README failuose paprastai yra keletas bendrų funkcijų. bendri modeliainors kiekvienas projektas išlaiko savo vizualinį ir turinio identitetą.

Įprasta rasti aiškus pavadinimas ir galimas viršelio paveikslėlis (pvz., projekto logotipas arba reklaminė juosta), po kurios pateikiami ženkleliai, apibendrinantys projekto būseną, licenciją, dabartinę versiją arba testavimo būseną. Tada paprastai pateikiamas projekto aprašymas, skyrius apie būseną (stabili, kuriama, eksperimentinė ir kt.) ir skyrius su demonstracijomis arba ekrano kopijomis.

Taip pat labai dažnai galima rasti bloką su prieiga prie projekto (nuorodos į įdiegtą versiją, dokumentaciją ir paskelbtus paketus), naudotų technologijų sąrašas, skyriai, skirti bendraautoriams, kūrėjams ir, žinoma, licencijaŠie elementai padeda README failui veikti tiek kaip trumpam vadovui vartotojams, tiek kaip vizitinei kortelei potencialiems bendradarbiams.

Kalbant apie dizainą, nors kalbame apie tekstinį failą, yra daug vietos, kad jis būtų lengviau skaitomas: naudokite gerai struktūrizuotas antraštes, sutvarkytus ir netvarkingus sąrašus, lenteles, kur tinka, ir Paryškintas tekstas pagrindinėms idėjoms pabrėžti„Markdown“ taip pat galite įterpti paveikslėlių, GIF ir mažų dekoracijų (pvz., jaustukų), kad būtų patogiau naudoti, visada atsižvelgiant į aiškumą.

Mažai aptarta gudrybė – visada rašyti galvojant apie ką nors, kas Jis absoliučiai nieko nežino apie projektą.Tai reiškia vengti prielaidų apie ankstesnes žinias, vartoti aiškią ir tiesią kalbą bei paaiškinti techninius terminus pirmą kartą jiems pasirodžius. Ir, žinoma, atnaujinti README failą, kai tik projekte įvyksta kas nors svarbaus.

Licencija, įnašai ir autorystė

Atvirojo kodo projektuose ypač svarbi README dalis yra skirta licencijaKodo publikavimas viešojoje saugykloje automatiškai netampa laisva programine įranga; būtina aiškiai nurodyti, kokiomis sąlygomis ji gali būti laikoma laisva programine įranga. būti naudojamas, modifikuojamas ir platinamas.

Dažniausiai naudojama gerai žinoma licencija (MIT, Apache, GPL, „Creative Commons“ dokumentacijai ir kt.) ir nuoroda iš README failo į saugyklos LICENSE arba COPYING failą. Tokiu būdu kiekvienas susidomėjęs asmuo iš karto žino, ką gali daryti su kodu ir kokie yra jo įsipareigojimai (pavyzdžiui, priskyrimas, platinimas vienodu būdu, atsakomybės apribojimai ir kt.).

Kitas svarbus brandaus README blokas yra indėlio vadovasŠiame skyriuje paaiškinama, kaip kiti gali prisidėti prie projekto: stiliaus gairės, atnaujinimų užklausų pateikimo procesas, kaip pranešti apie klaidas, kokio tipo įnašai priimami ir kur koordinuojamas darbas. Kartais ši informacija pateikiama atskirame CONTRIBUTING.md faile, į kurį nuoroda pateikiama README faile.

Taip pat gera praktika yra padaryti matomą prisidedantys asmenys ir kūrėjaiKai kuriuose projektuose pateikiamos lentelės su avatarais ir vardais, susietais su jų profiliais, o kituose tiesiog išvardijami pagrindiniai vartotojai. Šis gestas ne tik įvertina atliktą darbą, bet ir palengvina tiesioginį kontaktą, jei kam nors reikia pasikalbėti su konkrečiu komandos nariu.

Galiausiai verta skirti kelias eilutes paaiškinimui kaip gauti pagalbos Ir kokie kanalai egzistuoja: „GitHub“ problemos, forumai, el. pašto sąrašai, pokalbiai ir kt. Jei projektas nesiūlo oficialios pagalbos, taip pat verta tai aiškiai nurodyti, kad būtų išvengta nesusipratimų.

Atsižvelgiant į visa tai, kas išdėstyta aukščiau, README failas tampa pagrindine bet kurio skaitmeninio projekto dalimi: Jame paaiškinama, kas tai yra, kaip jis veikia, kas jį prižiūri ir kokiomis sąlygomis jis gali būti naudojamas.Rūpinimasis savo turiniu ir jo atnaujinimas yra nedidelė investicija, kuri daro didelę įtaką tam, kaip kiti žmonės suvokia ir naudoja jūsų darbą.