How to use github for collaboration on writing and revising papers

… a set of step by step

Step 1. Set up a free github account, go here. Likewise, please ask your collaborators to get github accounts as well (if they do not have them already), or ask them to share their github usernames.

Step 2. In github, you can upload any file that you want to share with your collaborators. Let’s say you have written a paper called “mypaper1.docx”, a word document and you have several co-authors. You have submitted the paper to a journal and the journal editor has returned the paper for revision. You have revised and you want your co-authors to work on the paper as well. Now your revision is ‘mypaper1_rev.docx”. So, the first thing is for you to upload the paper to your new github site. You upload like this:

Click on add file and upload the file

So, your file now resides on your repository. Your collaborators can either directly edit the file OR they can download and work on their own, but they can only upload the file to your repository if you give them permission, or if they fork the repository to their own. Then they too will be able to upload the file to this repository. So,

Step 3. Your collaborators will also need to have their own github account and username (they can sign up and get a free account as you have done). But then, they will need to have access to the repository. Share the url to your github repository. When your collaborators reach your repository, they will see something like this:

They will see the link to the file I uploaded (the marked section)

How my collaborators will be able to edit and make changes?

From here, there are various ways:

  • If your file is a markdown file, then once your collaborators can access the file, they can directly edit the file
  • But your file is NOT a markdown file, it is a Word document. Your collaborators can download the file and make their own copies, change and then upload to this repository again. For this they will need to access this repository.
  • They can create ISSUES in github and that way you can keep track of all requested changes. This is a great way to collaborate. So, here are the steps:

Step 4. Once you are in github, click on issues. Create a new issue by clicking on the box

Step 5. The issue after completed, looks like this,

A sample issue raised

This way, you can keep track of issues associated with the paper and related changes, and you can effect them one by one when you revise or when anyone revises. So, either:

  • You do all the revisions or another person in your authorship team takes charge of revisions and marks them issue by issue and resolves them
  • Or, people can download the paper, make changes, and then upload them
  • Or, make a combination of both.

Associate Professor of Epidemiology and Environmental Health at the University of Canterbury, New Zealand. Also in:

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store