In line with the FAIR Principles for Research Software, effective documentation and version control are key to ensuring the usability and longevity of your research software. They make your software, code and digital outputs more Findable, Accessible, Interoperable, and Reusable.

Always Write a

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.


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

Create a

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).


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

Software Citation

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.


  • 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.
Consider Creating a Documentation Website

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



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

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


Visibility options

Public GitHub/Gitlab

UM Gitlab Installation

Departmental GitHub

(The department might be paying for a plan)

Public repositories Yes No Yes
Internal repos (only visible for UM employees) No Yes No (only the department’s staff)
Private repositories Yes Yes Yes
Privacy compliance No Yes Yes (depending on the plan the department is paying)


Some UM’s departmental github: