Why document your research software? 

Independent of where the documentation can be found, documentation is essential for reuse of software. It provides necessary information to understand what the research software does, how it can be reused, under which terms the software can be used, and how it needs to be cited.  Documentation for code and software may be found embedded within the code, i.e. code comments or as a separate README (e.g. a README.txt or README.cff) file. 

Recommended documentation for research software 

The following documentation is recommended for describing and explaining your research software:  

1. General information – project name, version number, creation date (range), short description of software’s purpose and functionality (e.g. tool for …. ) 

2. Project overview – detailed description of the software’s purpose and functionality, use cases when applicable, organisation of the project, size of the software files 

3. Installation – step-by-step instructions, system requirements, required dependencies (e.g. libraries, packages), setup requirements, potential issues  

4. Usage – instructions for running the software or execution of code, usage examples when applicable, description of how to run tests, potential issues 

5. Licence – a licence file, e.g. a LICENCE.cff 

6. Citation – a citation file, e.g a CITATION.cff  

7. Contact information – principal investigator, maintainer, developer, copyright owner 

8. Acknowledgements – funding sources when applicable, publications citing the software, location where software is available, contributors, list of related data, scripts, applications, etc.  

You can write the documentation, in whichever form, yourself. However, there is a WUR template for a README file available (applicable to both research data and software): https://doi.org/10.5281/zenodo.7701727. This template can be adapted to your needs for describing research software.  

Increase research software findability with metadata 

Metadata is machine-readable information that describes your research software. Metadata is indexed as information associated with your research software, which in turn increases its findability by ensuring it shows up when users search for software using terms included in your metadata. Enriching your metadata with keywords that describe your research software is therefore important for increasing its findability.  

Examples of metadata are creator(s) + affiliation(s), title, version, access rights, keywords, license, funder and/or grant, etc. Metadata can be added to the README file or when publishing the GitLab or GitHub repository in a data repository, e.g. Zenodo, 4TU.ResearchData, DANS Data Stations.  
 
Additionally, when using the repository Zenodo, you can add a .zenodo.json to your Git repository to describe the software. Then Zenodo uses the information in that file to describe the software. The advantage of using this file is that there is metadata in the .zenodo.json file that is not supported by the CITATION.cff file. To create a .zenodo.json file, have a look at Zenodo JSON file | Zenodo.  

Support 

Do you have questions about this service, or would you like personal support? Feel free to contact us. You can send an email to data@wur.nl.