From Data to Credits: Using ReadMe, Markdown, and Dublin Core for Better Documentation
Abstract
Howto for a simple ReadMe in flavor of the Love Data Week 2025 presented at SLUB Open Science Lab for using plain Markdown and Dublin Core to annotate your data . See the file "ReadMe.md" for an example. Furthermore, as this ReadMe follows a straightforward structure given by section and text, simplistic parsing can be used to extract and validate the metadata and to streamline the documentation process. One implementation of a parser written in python to convert Markdown to JSON files can be found here. Link to Poster: https://doi.org/10.5281/zenodo.15127381Link to Markdown-to-JSON-Parser: https://doi.org/10.5281/zenodo.14942696 and https://github.com/Bondoki/ParsingMetadataMD2JSON
Full text
From Data to Credits: Using ReadMe, Markdown, and Dublin Core for Better Documentation. The basics of the “ReadMe”: • provide a meta-data description of your project, so that you and other have a glimpse of idea what's inside your folder/files/repository – any information is better than nothing • root folder should have generic ReadMe followed by descriptive ReadMe in each subfolder • in the simplest way provide ASCII text file describing your work avoiding .docx or .odt • it is usually a simple plain-text file called READ.ME, README.TXT, ReadMe.md or README • often simple ReadMe.md formatted in the human readable Markdown markup language[1] • some guidance can be found in Ref.[2] and a list of best practice READMEs in Ref.[3] The contents of the “ReadMe”: • rule of thumb: document relevant details about data collection, processing, and analysis • minimum information: title, creator, contact, file naming convention, folder structure, description of data (5W1H+R[4]: What? When? Where? Who? Why? How? +Relationship), license, and ...as much information as possible Where to go from here: For interoperability of metadata use the Dublin Core standard[5] with XML-schema or JSON-LD[6]. References: [1] https://daringfireball.net/projects/markdown/syntax [2] https://www.makeareadme.com/ [3] https://github.com/matiassingers/awesome-readme [4] Subramaniam, Pranav / Ma, Yintong / Li, Chi / Mohanty, Ipsita / Fernandez, Raul Castro Comprehensive and Comprehensible Data Catalogs: The What, Who, Where, When, Why, and How of Metadata Management 2023, https://doi.org/10.48550/arXiv.2103.07532 [5] https://dublincore.org/resources/userguide/creating_metadata/ [6] https://en.wikipedia.org/wiki/JSON-LD
README.md # Title Paper/Project/Thesis/Dataset (The name given to the paper/project/thesis/dataset.) # Creator Jay Doe (Who created the resource and is primarily responsible? Can be a repetitive list of authors, artists, collectors, organizations etc.) # Creator.ORCID 0000-0001-2345-6789 (ORCID identifier of the Creator) # Creator.Email [email protected] (email identifier of the Creator) # Publisher Institute of Fancy Science Department of Amazing Science Imaginary Street 42 D-01234 ImaginaryTown Country (The department/institute responsible for making the resource available.) # Description Exemplary test case to verify the simulation tools and compare to the experiment. Data have been published at Zenodo under CC-BY 4.0, see https://zenodo.org/doi/10.5281/zenodo.XYZ . (A textual description of the content of the resource.) # Subject * Experimental Data * Abbreviation: NMR, SAXS * (Phrase\Keywords describing the content of the resource.) # Date 2025-02-14 (A date associated with the creation or availability of the resource. Recommended format: YYYY-MM-DD) # Language en-US; de-DE (The language of the resource recommended as BCP 47 language tag. # Format * csv * pdf * (The data format to identify the software and possibly hardware that might be needed to display or operate the resource. For a list of MIME types see [here](https://www.iana.org/assignments/media-types/media-types.xhtml)). # Method Method01XYZ hasURL https://github.com/FakeUser/FakeProject/releases/tag/v1.0 Method01XYZ hasDependency https://github.com/FakeProjectDependsOn/releases/tag/v2.2.2 Method01XYZ hasDOI https://doi.org/10.5281/zenodo.ZYX (Refer to your (post-)processing tools/methods, e.g. URL or git hash) # Type Text (The category of the resource e.g. Collection, Dataset, Event, Image, Experiment, Simulation, Report, Text, Draft, Image. See also [DCMI Type Vocabulary](https://www.dublincore.org/specifications/dublin-core/dcmiterms/#section-7/).) # Coverage 2024-2025 (Temporal coverage is typically a period for acquiring the data.) # Source PhD-Thesis IsPartOf https://doi.org/10.5281/zenodo.ABC (Information about a second resource from which the present resource is derived - if applicable.) # Relation Experiment IsPartOf PhD-Thesis PhD-Thesis IsReferencedBy https://doi.org/10.5281/DOI.OF.PAPER (An identifier to provide a relationship from source to the present resource, e.g. IsVersionOf, IsReplacedBy, IsPartOf, IsReferencedBy, see [Qualified Dublin Core Terms](https://www.dublincore.org/specifications/dublin-core/dcmi-terms/)) # Identifier https://doi.org/10.5281/zenodo.PUBLISHED_THESIS (An unique identifier of the resource, e.g. DOI, ISBN, Number) # Rights CC-BY-4.0 hasURL https://creativecommons.org/licenses/by/4.0/ (A rights management statement of the resource, e.g. license for publishing and sharing.) structured layout with minimal information including relational identifiers (similar to ✔ rdf-schema) simple parsing and machine processing is possible between ‘#’ section to archive interoperability ✔ minimal standard in analogy to Dublin Core identifiers ✔