Gestructureerde documentatie

Metadatastandaarden

Om consistente documentatie te produceren, hebben verschillende onderzoeksgemeenschappen metadatastandaarden opgesteld. Deze specificeren in detail de informatie die tijdens documentatie moet worden opgenomen om een bepaald dataobject, dataset of onderzoeksproject te beschrijven, volgens de behoeften van een specifieke gebruiker of wetenschappelijke gemeenschap.

De meeste metadatastandaarden zullen velden bevatten die gewijd zijn aan de beschrijving van de data, de technische vereisten die nodig zijn om ze opnieuw te gebruiken, informatie over licenties en intellectuele eigendomsrechten, en gebruikerstoegang. Hieronder volgt een samenvatting van de meest voorkomende soorten metadata die kunnen worden gebruikt om een onderzoeksproject te beschrijven:

(Bron: The ins and outs of metadata and data documentation)

Controlled Vocabularies

Om de creatie van metadata te optimaliseren, kun je controlled vocabularies (ofwel gecontroleerde woordenlijsten) gebruiken om de metadata-elementen in te vullen. Controlled vocabularies zijn georganiseerde en gestandaardiseerde woorden en zinsdelen die worden gebruikt om op een consistente manier data te beschrijven, te catalogiseren of te indexeren. Ze omvatten onderwerpkoppen, alfabetische lijsten, taxonomieën, thesauri of ontologieën. Het gebruik van een controlled vocabulary vergroot de vindbaarheid en deelbaarheid van je data met onderzoekers in dezelfde discipline. Controlled vocabularies die in verschillende gemeenschappen worden gebruikt, zijn:

• Arts & Humanities: Art & Architecture Thesaurus, Thesaurus of Musical Instruments
• Health Sciences & Medicine: International Classification of Disease (ICD), Medical Subject Headings (MeSH)
• Social Sciences: Ethnographic Thesaurus, Thesaurus for Economics

Naamgeving van bestanden

Door vooraf naamgevingsconventies af te spreken voor de bestanden en mappen die data zullen bevatten, kunnen jij en jouw team gemakkelijk door de inhoud, status en versie van de bestanden in je database navigeren. Een eerste overweging bij het kiezen van naamgevingsconventies is om ze zowel machineleesbaar als menselijk leesbaar te maken. De volgende tips helpen hierbij:

• Vermijd spaties, interpunctie, hoofdlettergevoeligheid en tekens zoals ?\!@*%{[<>.
• Maak gebruik van scheidingstekens. Gebruik een koppelteken (-) om 'verschillende woorden die deel uitmaken van hetzelfde stuk' aan te duiden en onderstrepingsteken (_) om verschillende stukjes metadata van elkaar te scheiden
• Kies trefwoorden en bestandsnamen die voldoende beschrijvend zijn, bijv. analysis01_descriptive-statistics.R, analysis02_preregistered-analysis.R
• Gebruik de datumnotatie JJJJ-MM-DD (ISO 8601-standaard)
• Om bestanden te sorteren, zet je eerst de datum of het nummer, bijv. 2019-01-01_original-analysis.R, 2019-12-01_minor-changes-to-original.R, 01_original-analysis.R, 02_minor-changes-to-original.R
• Voeg de versie van het bestand toe, bijvoorbeeld methodologiesectie_v1

Voor extra coherentie en consistentie kun je de gebruikte naamgevingsconventies beschrijven in een apart README-bestand. Je kunt naamgevingsconventies toepassen op bestanden en mappen met jouw data, zelfs als je de meeste al hebt gemaakt, door een hulpprogramma voor het hernoemen van bulkbestanden te gebruiken. Dit is een type software waarmee je dezelfde naamgevingselementen op meerdere bestanden kunt toepassen totdat je een consistente naamgevingsstructuur voor al je bestanden en mappen bereikt.

Versiebeheer

Versiebeheer is het proces van het vastleggen en beheren van verschillende concepten en versies van een document of een dataset. Het biedt een overzicht van de updates en revisies die hebben geleid tot de definitieve versie. Versiebeheer wordt geadviseerd wanneer er meer dan één versie van een document of een dataset bestaat (of wanneer dit waarschijnlijk in de toekomst zal gebeuren). Afhankelijk van de data waarmee je werkt, kan dit worden gedaan door:

• De datum opnemen in de bestandsnaamgeving, bijv. 2022-05-21_Health-test
• Volgnummers toevoegen aan het einde van de bestandsnaam, bijv. _v1, _v2, _v3
• Een versiebeheertabel maken met het aantal wijzigingen, de datum en hun doel
• Een tabblad "versiebeheer" toevoegen aan de spreadsheet met de kolommen versie, datum en wijzigingen
• Software voor versiebeheer gebruiken (bijv. Github, GitLab)
• Tools gebruiken die automatisch versies van je werk bewaren (bijv. Overleaf)

Tijdens het werken aan een project is het handig om te beslissen hoeveel versies van een bestand je wilt bewaren, welke versie je wilt bewaren, voor hoe lang en hoe je ze wilt ordenen. Je kunt bijvoorbeeld versies als mijlpaal identificeren en besluiten om alleen de grote revisies te behouden in plaats van alle kleine revisies. Het is handig om één naamgevingsconventie aan te houden, bijvoorbeeld datums of versienummers. Spreek één locatie af voor de opslag van masterversies.

README-bestand

Een README-bestand (ofwel leesmij-bestand) geeft informatie over een project of een dataset. Het helpt ervoor te zorgen dat de data correct kunnen worden geïnterpreteerd door jezelf (op een later tijdstip) of door anderen (bij het delen of publiceren van data). Meestal moet een README-bestand samen met de andere datasetbestanden worden ingediend. De belangrijkste overwegingen zijn:

• Maak een README-bestand voor elke dataset.
• Noem het bestand README (niet readme, read_me, ABOUT, enz.).
• Schrijf het als een gewoon tekstbestand en sla het op als README.txt (of README.md bij het schrijven in Markdown).

Advies op pagina's over datadocumentatie is samengesteld op basis van de informatie verstrekt door de RDNL, UK Data Service, CESSDA, the Finnish Social Science Data, Utrecht University, DCC and 4TU.ResearchData.

Deze pagina is voor het laatst bijgewerkt in januari 2023. Heb je niet-werkende links of (schijnbaar) onjuiste informatie gevonden? Stuur dan een e-mail met als titel 'Website content' naar datasteward@eur.nl.