Collaborative Writing

This tutorial provides a step-by-step guide to using R, RStudio, GitHub, and GitHub Desktop for collaborative manuscript writing. These tools facilitate collaboration and help keep track of the manuscript writing progress.

All necessary files for this tutorial are available here. If you’re new to Rmarkdown, consider revisiting the introductory tutorial.

GitHub Account

  • Visit GitHub and click “Sign up”, and follow the instructions to create your account.
  • On GitHub, click the “+” or “new” icon on the top right and select “New repository”.
  • Name your repository, add a description, initialize it with a README, and click “Create repository”.

Necessary Software

Cloning Repository

  • On GitHub Desktop, go to “File” > “Clone repository”,
  • choose the repository you want to clone and select the local path,
  • and click “Clone”.
  • Navigate to the local path and ensure all files are cloned.

Bookdown Template in RStudio

  • In RStudio, go to “File” > “New Project” > “New Directory” > “Book Project using bookdown”.
  • Name your project (e.g., “test1”) and create it.
  • Navigate to the project directory, copy all files, and paste them into your original repository folder.
  • Rename the project file to a suitable name (e.g., “template”).

Compiling

  • Open the index file in your RStudio project.
  • Update the YAML header and chapter/section names as per your manuscript.
  • Compile the document into HTML and/or PDF using the “Build” tab in RStudio.

Updating GitHub Repository

  • Make changes to your manuscript files in RStudio.
  • Open GitHub Desktop, review changes, commit them with a descriptive message, and push to the origin.

Publishing Using GitHub Pages

  • In your GitHub repository, create a new folder named “docs” and copy your compiled HTML files into it.
  • Go to the settings of your GitHub repository, navigate to “GitHub Pages”, and set the source to the “docs” folder.
  • Your manuscript will be available at “username.github.io/repository_name”.

Invite collaborators

To invite collaborators to a GitHub repository, begin by navigating to your desired repository and clicking on the “Settings” tab. In the left sidebar, select “Manage Access” and click “Invite a collaborator.” Enter the username, full name, or email of the person you wish to invite and select them from the suggestions. Assign a role to define their access level and send the invitation. The invitee can accept via the email link sent or directly through their GitHub account. You can review and manage all collaborators and pending invitations in the “Manage Access” section.

Video content (optional)

Tip

For those who prefer a video walkthrough, feel free to watch the video below, which offers a description of an earlier version of the above content.

Useful resources