Metadata en documentatie zijn belangrijk voor de vindbaarheid en herbruikbaarheid van onderzoekssoftware.

Waarom je onderzoekssoftware documenteren?

Goede documentatie van je onderzoekssoftware is belangrijk om het te kunnen hergebruiken. Je geeft daarmee de benodigde informatie om te begrijpen wat de onderzoekssoftware doet, hoe het gebruikt kan worden, onder welke voorwaarden en hoe het geciteerd moet worden. Documentatie voor code en software kan in de code zelf zijn opgenomen (code comments) of als een README bestand (bijvoorbeeld README.txt of README.cff) aan de software zijn toegevoegd. 

Aanbevolen documentatie voor onderzoekssofware

Voor het begrijpelijk maken van onderzoekssoftware wordt aangeraden het volgende op te nemen in de documentatie:

1. Algemene informatie – projectnaam, versie, datum/periode van ontwikkelen, korte beschrijving van het doel en functie van de software.
   
   
2. Beschrijving project – gedetailleerde beschrijving van het doel en functie van de software, use cases indien van toepassing, organisatie van software, grootte van de softwarebestanden.
   
   
3. Installatie – stap-voor-stap instructies, systeemvereisten, vereiste dependencies (zoals libraries en packages), setup vereisten, mogelijke problemen waar tegenaan gelopen kan worden.  
   
   
4. Gebruik – instructies voor het draaien van de software of uitvoeren van de code, use cases indien van toepassing, beschrijving van hoe testen uit te voeren, mogelijke problemen waar tegenaan gelopen kan worden.
   
   
5. Licentie – een licentie bestand zoals een LICENCE.cff
   
   
6. Citatie – een citatiebestand, zoals een CITATION.cff
   
   
7. Contact informatie – projectleider, beheerder, ontwikkelaar, eigenaar auteursrecht
   
   
8. Erkenning en bronvermelding – subsidieverstrekkers indien van toepassing, publicaties die de software citeren, waar de software beschikbaar is, bijdragers, gerelateerde en/of hergebruikte data, scripts, applicaties etc. 

Je kan zelf een documentatiebestand maken, maar er is ook een WUR-template beschikbaar voor een README-bestand dat voor zowel onderzoeksdata als onderzoekssoftware te gebruiken is, zie https://doi.org/10.5281/zenodo.7701727. Dit template kan aangepast worden aan de manier waarop jij je software wilt beschrijven. 

Verhoog de vindbaarheid van onderzoekssoftware met metadata

Metadata is informatie die je onderzoekssoftware beschrijft en machine leesbaar is. Het wordt geïndexeerd als informatie geassocieerd met je onderzoekssoftware waardoor de vindbaarheid wordt vergroot. Het is daarom belangrijk om metadata te verrijken met trefwoorden die je onderzoekssoftware beschrijven. Op deze manier kunnen anderen de software beter vinden. 

Andere toe te voegen metadata zijn o.a. de ontwikkelaar(s) + affiliatie(s), titel of naam, versie, toegangsrechten, licentie, subsidieverstrekker en/of beurs, etc. Metadata kan worden toegevoegd in het README-bestand of tijdens het publiceren van je GitLab of GitHub repository in een data repository zoals Zenodo, 4TU.ResearchData of DANS Data Stations. 

Daarnaast, wanneer je Zenodo gebruikt, kun je een .zenodo.json toevoegen aan je Git repository met informatie over je software. Zenodo gebruikt dan de informatie in dit bestand om de software te beschrijven. Het voordeel hiervan is dat er metadata in dit bestand zit, die niet is opgenomen in een CITATION.cff. Om een .zenodo.json bestaand aan te maken, kun je naar Zenodo JSON file | Zenodo gaan. 

Vragen en ondersteuning 

Heb je vragen over deze dienst of wil je persoonlijke ondersteuning? Neem gerust contact op met ons. Je kunt een mailtje sturen naar data@wur.nl.