Documentation and version control

This file, located at the root of your repository, is the first point of contact for users, researchers and your future self. It should contain:

• A short description of the software or code.
• A list of prerequisites to run it.
• Instructions on how to install the program locally.
• A few working examples that illustrate the program’s main features.
• Instructions on how to build and publish it, if applicable.

How?

Learn how to create a README.md file by following this module and use this template as an example.

This file, also located at the root of your repository, provides instructions for potential contributors. It should explain:

• Important file locations and comments on the general code structure.
• How to run in development and test the code.
• The process to submit a change (pull request requirements).

How?

Learn how to create a CONTRIBUTING.md file by following this module find an example here.

To ensure your software is properly credited, include a CITATION.cff file in the root directory of your software. This file provides information about how to cite the software.

How?

• Read more about the citation file format here.
• Watch this tutorial by the eScience Center to learn how to create a citation file.
• Find an implementation example here.

For extensive documentation, consider using a platform like GitHub Pages to create a user-friendly website.

How?

• Sources to get started: GitHub Pages, a guide to deploying your docs to various hosting providers
• An example of minimalistic documentation in using Github pages: Case Law Explorer (Maastricht Law and Tech Lab)

Tips:

• Make your GitHub Pages FAIR.
• Don’t include personal data in GitHub pages. It’s about documenting your code, not storing datasets.

Version Control Platforms like GitLab and GitHub allow for tracking changes, reverting to previous versions, and collaborative development. They also have the potential to attract research collaborators and improve work at an early stage

How?

• Official start with Git: Git Handbook
• IDS’s best practices
• Git tools overview at Maastricht University:

Some UM’s departmental github:

• https://github.com/MaastrichtU-Library
• https://github.com/MaastrichtU-IDS
• https://github.com/maastrichtlawtech
• https://github.com/MaastrichtU-CDS
• https://github.com/MaastrichtU-BISS
• https://github.com/BiGCAT-UM
• https://github.com/M4I-nanoscopy
• https://github.com/macsbio