Wat zijn README-bestanden en hoe gebruik je ze correct?

Als je met digitale projecten werkt, kom je vroeg of laat een bestand tegen met de naam... READMEHoewel het misschien een eenvoudig tekstdocument lijkt, is het veel belangrijker dan het op het eerste gezicht lijkt: het is de sollicitatiebrief voor uw projectHet is het eerste aanspreekpunt voor iedereen die wil weten wat je hebt gedaan, hoe je het kunt gebruiken en of het de moeite waard is.

In de wereld van softwareontwikkeling, datawetenschap, of zelfs in academisch werk en samenwerkingsprojecten, is een README goed geschreven Het bespaart je tijd, voorkomt fouten en maakt het voor anderen (of zelfs voor jezelf over een paar maanden) gemakkelijker om snel het doel van het project te begrijpen. Laten we eens nader bekijken wat README-bestanden zijn, waar ze voor dienen, wat ze zouden moeten bevatten en hoe je er het meeste uit kunt halen.

Wat is een README-bestand precies?

Een README-bestand is een tekstdocument dat bij een digitaal project hoort Het hoofddoel is om duidelijk uit te leggen wat het project inhoudt, waar het voor dient en hoe het te gebruiken is. Letterlijk vertaald zou het zoiets zijn als "lees mij", en dat is precies de functie ervan: het eerste zijn wat iemand leest wanneer hij een repository, een datafolder of een softwarepakket opent.

Dit type bestand kan op verschillende manieren worden opgeslagen. tekstformaten: van de klassieker readme.txt (platte tekst) tot readme.doc, readme.1st of minder gangbare uitbreidingen zoals . MijHet specifieke formaat wordt doorgaans aangepast aan besturingssysteem en het programma waarmee het wordt weergegevenzodat elke gebruiker het bestand zonder problemen kan openen en lezen.

Tegenwoordig, met name in softwareprojecten en code repositories, is het meest voorkomende formaat README.mdDe extensie .md geeft aan dat het bestand is geschreven in MarkdownHTML is een zeer eenvoudige opmaaktaal waarmee je tekst kunt omzetten naar HTML met slechts een paar symbolen voor de opmaak. Dit maakt het opmaken van de inhoud een stuk eenvoudiger. gemakkelijk te lezen, zowel in onbewerkte als in bewerkte vorm op een website.Daarnaast is het mogelijk om zonder problemen titels, lijsten, links, tabellen, afbeeldingen en meer toe te voegen.

Een goed gestructureerde README biedt de gebruiker of bijdrager een een complete en begrijpelijke samenvatting van het projectDit document is niet bedoeld als een uitputtende handleiding, maar als een praktische gids: wat het project doet, waarom het nuttig is, hoe je ermee aan de slag kunt en waar je meer informatie kunt vinden als dat nodig is.

In de datawereld, bijvoorbeeld bij datasetrepositories, is het heel gebruikelijk dat de README (soms in een ander formaat) readme.txt) verzamelen Algemene informatie, auteurschap, trefwoorden, geografische en temporele dekking, gebruikslicentie en methodologie. gebruikt om de gegevens te genereren of te verzamelen, evenals de Aanbevolen software om mee te werken..

Een korte geschiedenis en standaardgebruik van README-bestanden

Hoewel we ze tegenwoordig vooral associëren met platforms zoals GitHub, stamt de gewoonte om een ​​README-bestand in softwarepakketten op te nemen uit een andere tijd. tientallen jaren geledenEr zijn gedocumenteerde voorbeelden die teruggaan tot... midden jaren zeventig, toen programma's al werden verspreid met een klein documentje waarin de inhoud en het gebruik ervan werden uitgelegd.

Na verloop van tijd raakte de praktijk zo ingeburgerd dat in de GNU-coderingsstandaarden (GNU-coderingsstandaarden) het README-bestand wordt beschouwd als een vereisteDeze standaarden hebben een grote invloed gehad op het ecosysteem van vrije software en hebben ertoe bijgedragen dat het README-bestand bijna verplicht is geworden in elk serieus softwarepakket.

Toen het web de standaardplatform voor het distribueren van softwareVeel projecten begonnen een deel van de informatie die voorheen in de README stond (handleidingen, licentie, nieuws, enz.) te verplaatsen naar websites, wiki's of andere platforms. broncode tarball-pakketDesondanks verdween het README-bestand nooit helemaal: in veel gevallen bleef het bestaan. lokale samenvattinghoewel het soms nog enigszins onvolledig was in vergelijking met de online documentatie.

De populariteit van platforms zoals GitHub En dankzij de inspanningen van meer gevestigde open source-gemeenschappen zijn README-bestanden weer op de voorgrond getreden. Op GitHub bijvoorbeeld, als een repository een README-bestand in de hoofdmap bevat, voegt het systeem dit automatisch toe. Het wordt automatisch omgezet naar HTML en weergegeven op de homepage. van het project, dus het is het eerste wat je ziet als je binnenkomt.

Bovendien wordt het begrip "readme-bestand" soms gebruikt in een algemeen Een README-bestand verwijst naar elk kort document dat de inhoud van een map of project uitlegt, zelfs als het bestand niet letterlijk README heet. Veel open source-softwareprojecten distribueren een standaard set bestanden samen met het README-bestand, elk met een duidelijk omschreven functie.

Typische bestanden die bij een README-bestand horen.

Bij projecten die aan bepaalde normen voldoen, zoals Gnits-standaarden of die gegenereerd zijn met tools zoals GNU AutotoolsNaast het hoofd-README-bestand vind je vaak ook andere tekstbestanden die de projectinformatie aanvullen. Enkele van de meest voorkomende zijn:

• READMEAlgemene informatie over het project, het doel en de algemene visie.
• AUTEURS: lijst van belangrijkste auteurs of medewerkers.
• BEDANKT: dankbetuigingen aan personen of instellingen die hebben geholpen.
• CHANGELOGEen gedetailleerd wijzigingslogboek, voornamelijk bedoeld voor ontwikkelaars.
• NIEUWSEen beknopter en begrijpelijker wijzigingslogboek voor eindgebruikers.
• INSTALL: specifieke installatie-instructies en technische vereisten.
• KOPIËREN / LICENTIE: tekst van de softwarelicentie voor gebruik en distributie.
• BUGSBekende fouten en manieren om deze correct te melden.
• FAQVeelgestelde vragen en hun antwoorden.
• ALLES: lijst met openstaande taken en geplande toekomstige verbeteringen.

Al deze documenten, samen met het README-bestand, vormen het raamwerk van de basisdocumentatie van veel pakketten. In sommige gevallen is een deel van deze informatie zowel in de repository als op de projectwebsite gedupliceerd om de toegang vanuit verschillende kanalen te vergemakkelijken.

De rol van README op GitHub en vergelijkbare platforms

Op GitHub speelt het README-bestand een bijzonder belangrijke rol. Om te beginnen is het meestal het eerste wat iemand ziet dat bezoekt jouw repositoryAls het bestand goed is opgesteld, is binnen enkele seconden duidelijk wat het project doet, waarom het interessant kan zijn, hoe je het kunt opzetten en gebruiken, en wie erachter zit.

GitHub herkent het README-bestand automatisch wanneer het op bepaalde locaties in de repository wordt geplaatst. Als je het in de map plaatst, .github, In de root directory of in de map docshet platform detecteert het en prominent weergegeven voor bezoekers. Wanneer er meerdere README-bestanden zijn, volgt GitHub een volgorde van prioriteit: eerste zoekopdracht in .github, vervolgens bij de wortel en uiteindelijk bij docs.

Bovendien, als u een openbare repository aanmaakt waarvan de naam exact overeenkomt met uw gebruikersnaam En als je een README-bestand aan de root toevoegt, wordt dat bestand automatisch je Profiel READMEHet wordt weergegeven op je gebruikerspagina, waardoor je een aangepaste presentatiesectie kunt maken met behulp van GitHub Flavored Markdown.

Wanneer een README-bestand (of een ander .md-bestand) op GitHub wordt bekeken, genereert het platform automatisch een Inhoudsopgave Gebaseerd op de titels van de documenten. U kunt deze index bekijken door op het pictogram 'Overzicht' te klikken. Dit maakt het veel gemakkelijker om door lange README-bestanden met meerdere secties te navigeren.

GitHub staat ook toe link direct naar specifieke sectiesElke kop genereert automatisch een link; als je met de muis over de titel beweegt, verschijnt het linkpictogram. Hiermee kun je URL's delen die direct verwijzen naar het specifieke gedeelte van de README dat je wilt uitlichten (bijvoorbeeld het installatie- of bijdragen-gedeelte).

Er is één belangrijk praktisch detail: om prestatieproblemen te voorkomen, als uw README-bestand de 500 KiB qua grootte, GitHub zal de inhoud inkorten Vanaf dat moment in de weergegeven weergave. Daarom wordt aangeraden om de README te reserveren voor essentiële informatie en lange handleidingen of tutorials naar wiki's of aparte documentatie te verplaatsen.

Opmaak en links binnen een README-bestand

Om de README gemakkelijk te onderhouden en goed te laten werken op zowel GitHub als lokale klonen, wordt aanbevolen om het volgende te gebruiken: relatieve links en afbeeldingspaden relatief ten opzichte van het bestand waarin ze zich bevinden. Dus, bijvoorbeeld, als je een README-bestand in de hoofdmap hebt en een document docs/CONTRIBUTING.mdDe link in het README-bestand zou er ongeveer zo uitzien: (docs/CONTRIBUTING.md).

Dit type relatieve link betekent dat bij het wisselen van branches of het klonen van de repository, De routes blijven correct functioneren. zonder dat ze aangepast hoeven te worden. GitHub zorgt intern voor de transformatie van deze paden, zodat ze verwijzen naar de juiste bestandsversie op basis van de weergegeven branch. Paden die beginnen met /die worden geïnterpreteerd ten opzichte van de root van de repository, evenals veelgebruikte operatoren zoals ./ o ../.

Het is belangrijk dat de verbind tekst Houd de link op één regel, want het verdelen over meerdere regels kan problemen veroorzaken. Vermijd bovendien absolute links naar interne bestanden in de repository, omdat deze kunnen breken als de basis-URL verandert of er een fork wordt aangemaakt.

Wat de reikwijdte van het document betreft, is het belangrijk te onthouden dat de README alleen de volgende informatie mag bevatten: de essentiële informatie om te beginnen met gebruiken en bijdragen voor het project. Voor uitgebreide documentatie (gebruikershandleidingen, complete API-gidsen, enz.) is het overzichtelijker om een wiki of een apart documentatiesysteem, dat vanuit het README-bestand zelf is gelinkt.

Wat is nu eigenlijk het doel van een README-bestand?

Naast de theorie functioneert het README-bestand in de praktijk als volgt: eerste leidraad en referentiepuntHet is niet de bedoeling om uitgebreide formele documentatie te vervangen, maar eerder om een ​​ordelijke en praktische uitleg te geven van de belangrijkste aspecten van het project.

Tot de meest voorkomende toepassingen behoren: Leg het doel uit Beschrijf het project, welke gegevens of bestanden het bevat, geef aan hoe het in gebruik genomen kan worden en specificeer de belangrijkste technische vereisten. Vermijd fouten die ontstaan ​​door onjuist gebruik.Wanneer meerdere gebruikers aan dezelfde code of data werken, voorkomt een duidelijke README-file eindeloze herhaalde vragen.

Bij gezamenlijke projecten, met name in grote teams of open source-gemeenschappen, is de README bijna een essentieel onderdeel van het project. component van de communicatie-infrastructuurHet dient om de verwachtingen op elkaar af te stemmen, de mate van volwassenheid van het project aan te geven, te definiëren hoe men bijdraagt ​​en te verduidelijken welke ondersteuning wordt geboden (indien van toepassing).

Zelfs bij persoonlijke projecten, zelfs als je er alleen aan werkt, fungeert een goed geschreven README als een langetermijngeheugenNa verloop van tijd vergeet je gemakkelijk beslissingen, afhankelijkheden of installatiestappen; door dit te documenteren voorkom je dat je je project maanden later opnieuw moet "ontdekken".

Daarom is de README niet zomaar een formaliteit: het is een praktisch hulpmiddel dat de prestaties verbetert. organisatie, communicatie en onderhoudbaarheid van elk type digitaal project.

Wanneer is het gepast om een ​​README-bestand aan te maken?

Het korte antwoord is dat het een goed idee is om een ​​README-bestand te maken. telkens wanneer er een project is dat gebruikt, beoordeeld of onderhouden gaat worden. door iemand anders dan de oorspronkelijke maker... en dat geldt ook voor je toekomstige zelf. Het hoeft geen enorme open-source repository te zijn: het hoeft alleen maar een zekere complexiteit te hebben of de inhoud moet vragen oproepen.

Enkele voorbeelden waarbij een README-bestand bijzonder nuttig is, zijn: web- of programmeerprojectenwaarbij het raadzaam is om de vereisten, ontwikkelingsprocessen, opstartopdrachten en de runtime-omgeving uit te leggen. Het is ook erg interessant in mappen met belangrijke gegevensom te verduidelijken wat die gegevens precies voorstellen, waar ze vandaan komen en wat de mogelijke beperkingen zijn.

Andere typische contexten zijn de websites gehost op een hostingdie vaak een README-bestand met implementatie-instructies bevatten, of de academische en technische werkenwaarin de README scripts, experimenten, gebruikte toolversies of instructies voor het reproduceren van resultaten kan beschrijven.

En samenwerkingsprojectenOf het nu intern of openbaar is, de README is vrijwel verplicht. Het helpt nieuwe mensen om soepeler aan het project deel te nemen en dient als gedeelde referentie om consistente gebruiks- en bijdragenormen te handhaven onder alle betrokkenen.

Welke informatie moet een goede README bevatten?

Een effectief README-bestand hoeft niet lang te zijn, maar het moet wel de volgende informatie bevatten: goed georganiseerd en heel duidelijkEr is een aantal basisgegevens die vrijwel altijd opgenomen moeten worden, en andere optionele inhoud die, afhankelijk van het type project, veel toegevoegde waarde kan bieden.

De meeste goed gedocumenteerde repositories en pakketten bevatten minimaal het volgende: projectnaam, A korte beschrijving van het doeleen samenvatting van de inhoud van de repository, de Instructies voor het gebruik of de installatie ervan en de essentiële vereisten (afhankelijkheden, minimale taalversie, besturingssysteem, enz.).

Het is ook ten zeerste aan te raden om er wat aan toe te voegen. contact- of ondersteuningsmethodeZelfs als het slechts een e-mail is of een link naar de sectie 'Problemen' van de repository, helpt dit iedereen die problemen ondervindt te bepalen waar en hoe ze deze kunnen melden, in plaats van dat ze verdwaald raken en niet weten met wie ze contact moeten opnemen.

Naast de basisinformatie is het vaak nuttig om ook informatie over de volgende zaken op te nemen: aanmaakdatum of versie actueel, de lijst van auteurs of verantwoordelijke partijen, de gebruik licentie en eventuele relevante mededelingen over het gebruik van de gegevens of code (bijvoorbeeld of het een experimentele versie is of niet geschikt voor productie).

De volgorde heeft ook invloed op de leesbaarheid: de belangrijkste informatie (wat het project is, waar het voor dient, hoe het gebruikt wordt) moet als eerste verschijnen. aan het begin van het documentSecundaire details, uitgebreide aftitelingen of historische aantekeningen worden voor later bewaard. Op deze manier krijgt iemand die alleen maar aan het browsen is in één oogopslag een duidelijk beeld.

Typische inhoud van een README-bestand in software

In softwareprojecten gaan README-bestanden vaak een stap verder en bevatten ze verschillende extra thematische blokken. In veel gevallen geeft het bestand een korte samenvatting van... installatie-instructies, installatie-instructies, basisgebruiksaanwijzingen, een bestandsmanifest (Leg uit waarvoor elke belangrijke map dient) en een samenvatting van de licentie.

Het is ook gebruikelijk om een ​​sectie op te nemen met informatie over de ontwikkelaar of het teamMogelijke manieren om bij te dragen aan het project, een lijst met bekende fouten en een korte handleiding voor het oplossen van veelvoorkomende problemen. Dit alles helpt iedereen die de repository bezoekt om... een mondiale en praktische visie zonder elders te hoeven zoeken.

In sommige gevallen kan het README-bestand een kleine Wijzigingslogboek Of verwijzen naar een extern CHANGELOG-bestand. Het is ook vrij gebruikelijk om een ​​"Nieuws" of "Wat is nieuw"-sectie op te nemen waarin relevante wijzigingen tussen versies worden uitgelicht, vooral wanneer de doelgroep eindgebruikers zijn in plaats van ontwikkelaars.

In de context van academische of data-archieven wordt, naast de inhoudsbeschrijving, in veel sjablonen aanbevolen om ook een beschrijving te geven. de methodologie voor het verzamelen of genereren van de gegevensde opgenomen variabelen, het tijds- en geografische bereik van de informatie, en eventuele relevante beperkingen op het gebruik of de interpretatie ervan.

De README als communicatiemiddel op GitHub

Wanneer je een project uploadt naar GitHub, wordt de README niet alleen documentatie, maar ook een communicatie- en presentatie-elementSterker nog, het platform zelf raadt aan om een ​​README-bestand toe te voegen aan elke openbare repository, zodat bezoekers snel begrijpen waar het project over gaat.

Je kunt de README gebruiken om dit uit te leggen. wat het project doetWaarom het nuttig kan zijn, hoe je ermee aan de slag kunt (bijvoorbeeld met een "Aan de slag"-sectie), waar je hulp kunt vinden (problemen, forums, chat, enz.) en wie de code actief onderhoudt. Dit alles beïnvloedt de waargenomen kwaliteit en het vertrouwen dat de repository genereert.

In veel gevallen gebruiken ontwikkelaars hun GitHub-repositories als professionele portfolioIn deze context maken goed opgestelde README-bestanden een enorm verschil: ze stellen recruiters of andere geïnteresseerden in staat om in één oogopslag de omvang van het project, de gebruikte technologieën en de werkwijze van de auteur te zien.

Als het niet je bedoeling is om bijdragen aan te trekken of de repository te promoten (bijvoorbeeld als het een privé- of zeer intern project is), is een zeer gedetailleerde README niet verplicht. Desondanks is het meestal wel praktisch om er minstens één te onderhouden. minimale basisdocumentatie Voor persoonlijk en teamgebruik.

GitHub biedt ook een aantal specifieke hulpprogramma's voor de README: het genereert automatisch een index, ondersteunt badges en pictogrammen en stelt je in staat afbeeldingen, GIF's of video's in te voegen om het project te presenteren. Effectief gebruikt kunnen al deze elementen de README aanzienlijk verbeteren. aantrekkelijker en gemakkelijker te navigeren.

Hoe structureer en verbeter je je README-bestand?

Bij het analyseren van populaire repositories (bijvoorbeeld projecten van grote technologiebedrijven of ruimtevaartorganisaties) valt op dat hun README-bestanden vaak een aantal overeenkomsten vertonen. gemeenschappelijke patronenhoewel elk project zijn eigen visuele en inhoudelijke identiteit behoudt.

Het is gebruikelijk om een Een duidelijke titel en eventueel een omslagafbeelding. (zoals een logo of banner voor het project), gevolgd door enkele badges die de status van het project, de licentie, de huidige versie of de teststatus samenvatten. Daarna volgt meestal een projectbeschrijvingeen sectie over de status (stabiel, in ontwikkeling, experimenteel, enz.) en een sectie met demonstraties of schermafbeeldingen.

Het komt ook vaak voor dat je een blok aantreft met toegang tot het project (links naar de geïmplementeerde versie, documentatie en gepubliceerde pakketten), een lijst met gebruikte technologieën, secties gewijd aan bijdragers, ontwikkelaars en natuurlijk de licentieDeze elementen zorgen ervoor dat de README zowel als een snelle handleiding voor gebruikers als een visitekaartje voor potentiële bijdragers functioneert.

Wat betreft het ontwerp: hoewel het om een ​​tekstbestand gaat, is er genoeg ruimte om het leesbaarder te maken: gebruik goed gestructureerde kopjes, geordende en ongeordende lijsten, tabellen waar nodig, en Vetgedrukte tekst om belangrijke ideeën te benadrukkenIn Markdown kun je ook afbeeldingen, GIF's en kleine versieringen (zoals emoji's) invoegen om de tekst gebruiksvriendelijker te maken, waarbij je altijd de duidelijkheid in gedachten houdt.

Een weinig besproken truc is om altijd te schrijven met iemand in gedachten die... Hij weet absoluut niets van het project af.Dit betekent dat je geen aannames doet over voorkennis, duidelijke en directe taal gebruikt en technische termen meteen uitlegt wanneer ze verschijnen. En natuurlijk moet de README worden bijgewerkt wanneer er iets relevants verandert in het project.

Licentie, bijdragen en auteurschap

Bij open source-projecten is een bijzonder belangrijk onderdeel van de README het gedeelte dat gewijd is aan de licentieHet publiceren van code in een openbare repository betekent niet automatisch dat het vrije software is; het is noodzakelijk om expliciet aan te geven onder welke voorwaarden het als vrije software kan worden beschouwd. voor gebruik, aanpassing en herdistributie..

De meest gangbare praktijk is het gebruik van bekende licenties (MIT, Apache, GPL, Creative Commons voor documentatie, enz.) en een link vanuit het README-bestand naar het LICENSE- of COPYING-bestand van de repository. Op deze manier weet iedereen die geïnteresseerd is direct wat ze met de code mogen doen en wat hun verplichtingen zijn (bijvoorbeeld naamsvermelding, delen onder dezelfde voorwaarden, beperkingen van aansprakelijkheid, enz.).

Een ander belangrijk onderdeel van een volwaardig README-bestand is de bijdragehandleidingIn dit gedeelte wordt uitgelegd hoe anderen kunnen bijdragen aan het project: stijlrichtlijnen, de procedure voor het indienen van pull requests, hoe bugs te melden, welke soorten bijdragen worden geaccepteerd en waar de werkzaamheden worden gecoördineerd. Soms staat deze informatie in een apart CONTRIBUTING.md-bestand waarnaar vanuit de README wordt verwezen.

Het is ook goede praktijk om de zichtbaar te maken bijdragende individuen en ontwikkelaarsSommige projecten bevatten tabellen met avatars en namen die gekoppeld zijn aan de profielen van de gebruikers, terwijl andere projecten alleen de belangrijkste gebruikers vermelden. Dit gebaar is niet alleen een blijk van waardering voor het werk, maar maakt ook direct contact mogelijk als iemand met een specifiek teamlid wil spreken.

Tot slot is het de moeite waard om een ​​paar regels te wijden aan de uitleg van hoe krijg ik hulp? En welke kanalen zijn er beschikbaar: GitHub-issues, forums, mailinglijsten, chats, enz. Als het project geen officiële ondersteuning biedt, is het ook belangrijk om dit duidelijk aan te geven om misverstanden te voorkomen.

Gezien al het bovenstaande wordt het README-bestand een essentieel onderdeel van elk digitaal project: Het legt uit wat het is, hoe het werkt, wie het onderhoudt en onder welke voorwaarden het gebruikt kan worden.Zorg dragen voor je content en deze actueel houden is een kleine investering die een groot verschil maakt in hoe anderen je werk waarnemen en gebruiken.