Hoe gebruik je een README-template voor elk nieuw onderzoeksproject

Stel je voor: je start een gloednieuw onderzoek, je hebt data, code, notities, bestanden overal.

En dan, zes maanden later, probeer je terug te vinden wat precies in dat ene scriptje staat of waarom je die specifieke versie van een dataset gebruikte. Klinkt bekend? Daar komt een README-bestand precies om het hoofd bieden. En met een goede template hoef je niet elke keer het wiel opnieuw uit te vinden.

Wat is een README-bestand en waarom is het zo belangrijk?

Een README-bestand is in feite de voorkant van je onderzoeksproject. Het is meestal een simpel tekstbestand, vaak in Markdown-formaat, dat je in de hoofdmap van je project zet.

Het vertelt iedereen, inclusief jezelf in de toekomst, wat het project doet, hoe het werkt en wat je nodig hebt om het te gebruiken. Binnen Open Science is dit essentieel.

Als je onderzoek reproduceerbaar wilt zijn, moet iemand anders, of jezelf over een jaar, in staat zijn om met minimale moeite te begrijpen wat er is gedaan. Een README-bestat is daar het startpunt van. Denk aan het als de kaft van een boek: als die er niet staat, pakt vrijwel niemand het boek op.

Waarom een template gebruiken in plaats van elke keer opnieuw beginnen?

Je zou elke keer een README kunnen schrijven vanuit het niets, maar waarom zou je?

Een template bespaart je tijd, zorgt voor consistentie tussen projecten en zorgt dat je geen belangrijke onderdelen vergeet. Universiteiten en onderzoeksinstellingen zoals de VSNU en DANS raden het gebruik van gestandaardiseerde templates aan als onderdeel van goede onderzoekspraktijken. Een template dwingt je ook om na te denken over dingen die je misschien zou overslaan.

Bijvoorbeeld: welke licentie gebruik je? Waar zijn de data te vinden?

Wie hebben eraan bijgedragen? Juist die details maken het verschil tussen een project dat herbruikbaar is en een project dat in een digitale la belandt.

Wat zit er in een goede README-template voor onderzoeksprojecten?

Een effectieve template bevat meerdere secties. Hieronder de belangrijkste: Begint met een duidelijke titel en een paar zinnen over wat het project doet.

Projecttitel en beschrijving

Niet te lang, niet te kort. Iemand moet binnen tien seconden begrijpen waar het over gaat.

Installatie en vereisten

Welke software heb je nodig? Python 3.9? R versie 4.2? Specifieke packages? Vermeld het hier. Geen uitgehandleiding, maar wel voldoende informatie zodat iemand het project kan opzetten zonder urenlang te zoeken. Hoe voer je de code uit? Welke commando's gebruik je?

Gebruiksinstructies

Welk bestand run je eerst? Dit hoeft niet uitputtend te zijn, maar een paar voorbeelden helpen enorm.

Databeschrijving

Welke data gebruikt het project? Waar komt de data vandaan? Is het openbaar beschikbaar, of zijn er toegangsbeperkingen?

Licentie

Vermeld ook de structuur van de data als dat relevant is. Maak een heldere data dictionary om de FAIR-principles te ondersteunen: data moet Findable, Accessible, Interoperable en Reusable zijn. Welke licentie hebt je gekozen?

Contactgegevens en bijdragen

Creative Commons, MIT, Apache? Dit is vaak over het hoofd gezien, maar cruciaal.

Changelog of versiegeschiedenis

Zonder licentie is het voor anderen onduidelijk of en hoe ze jouw werk mogen gebruiken. Wie heeft eraan gewerken? Wie kan men benaderen met vragen?

Citatie-instructies

Dit bevordert samenwerking en geeft credit waar credit toe behoort. Een korte notitie over wanneer er wijzigingen zijn gemaakt en wat er is veranderd.

Mappenstructuur

Dit is vooral handig als meerdere mensen aan een project werken. Hoe moet iemand jouw project citeren?

Status van het project

Dit is binnen de academische wereld belangrijk en wordt veel te vaak vergeten in README-bestanden. Een korte uitleg van de logische mappenstructuur voor je onderzoeksproject.

Bekende problemen of beperkingen

Wat staat in data/, wat in scripts/, wat in output/? Dit helpt anderen om snel te navigeren. Is het project afgerond, nog in ontwikkeling, of opgehouden? Dit voorkomt verwarring bij mensen die het project later tegenkomen.

Dankwoord en financiering

Zijn er dingen die nog niet werken? Zijn er beperkingen in de data of methodologie?

Gerelateerde projecten of publicaties

Wees hier eerlijk over. Transparantie is een kernwaarde van Open Science. Wie heeft het project gefinancierd?

Contributing guidelines

Zijn er personen of organisaties die je wilt bedanken? Dit is niet alleen beleefd, maar ook een vereiste van veel subsidiegevers.

Zijn er papers, datasets of andere projecten die gerelateerd zijn? Vermeld ze kort zodat mensen de bredere context kunnen zien.

Code of conduct

Als je jouw onderzoeksbestanden goed wilt organiseren zodat anderen kunnen bijdragen, leg dan kort uit hoe dat werkt. Welke standaarden hanteerden jullie? Hoe dien je wijzigingen in? Voor grotere projecten is het waardevol om kort aan te geven welke gedragsnormen gelden voor bijdragers.

Hoe zet je het in de praktijk?

De makkelijkste manier is om een standaard README-template te maken in een teksteditor of in GitHub. Sla het op als README-template.md in een centrale map op je computer of in een gedeelde drive. Elke keer dat je een nieuw project start, kopieer je het template en vul je de secties in.

GitHub, GitLab en Bitbucket ondersteunen Markdown-formaat, wat betekent dat je tekst er mooi uitziet zonder veel moeite.

Je kunt ook tools zoals Cookiecutter gebruiken om projectstructuren, inclusief README's, automatisch te genereren. Een praktische tip: vul het README-bestand in vanaf dag één van je project.

Niet later, niet als je klaar bent. Want dan weet je precies waarom je bepaalde keuzes maakte. Die context verlies je sneller dan je denkt.

Template aanpassen aan je project

Niet elk project is hetzelfde. Een statistisch analyseproject heeft andere noden dan een literatuurstudie of een softwaretool. Pas je template dus aan op basis van het type project.

Houd de kernsecties erin, maar voeg specifieke onderdelen toe waar dat logisch is.

Als je werkt met gevoelige data, voeg dan een sectie over dataveiligheid en privacy toe. Als je software ontwikkelt, denk dan aan tests en documentatie. Het idee is dat je template een levend document is dat meegroeit met je onderzoekspraktijk.

De grote lijn: maak het jezelf en anderen makkelijk

Uiteindelijk draait het allemaal om één ding: helder communiceren over je onderzoek.

Een goede README-template is geen bureaucratische last, maar een investering in de bruikbaarheid en duurzaamheid van je werk. Het kost je misschien een uur extra aan het begin van een project, maar bespaart uren, misschien dagen, aan verwarring later.

Open Science begint niet met grote beleidsplannen. Het begint met simpele, consistente dingen. Zoals een goed README-bestand bij elk project. Dus maak die template aan, gebruik hem bij elk nieuw onderzoek, en je zult je afvragen waarom je het niet eerder deed.