1  Preparation before the workshop

Before we can get to the fun stuff, you will need to download a few pieces of software to your computer to focus on creating in the workshop. If you have any problems, just message me on Teams.

1.1 Creating an online book workflow

For an overview to show why you need the following the pieces of software, you will follow this workflow to create and edit the book.

1.1.1 Creating the book

  1. Install the booktem R package.

  2. In RStudio, use the create_book() function to create a new project in your working directory containing the initial template files.

  3. Edit the basic details of your book, like the title, author(s), and description.

  4. Create a new github repository for your book folder.

  5. Publish the initial repository so the code is available on github.

  6. Activate github pages to render the book online via a URL.

1.1.2 Editing the book

  1. Open the book .Rproj file to start working on the book in RStudio.

  2. Edit or add chapter files in RStudio, specifying their order in the _quarto.yml file.

  3. Render individual chapter files as you work on them. Render index.qmd when you want to update all the chapters, or render them one by one to ensure all new changes are available.

  4. Add commits at key points using git/github to mark milestones with useful commit messages.

  5. When you want the book updating, push the changes to be available on github and your book URL after a short delay.

1.2 Download R and RStudio

If you are new to R/RStudio, you will need to install both pieces of software which is normally pretty straightforward. You might find this YouTube video here useful.

If you are a more experienced R/RStudio user, just make sure you update your version of R/RStudio as the booktem package will only work for recent versions as Posit are rapidly developing Quarto. I am currently using R version 4.4.1 (2024-06-14 ucrt) and RStudio 2023.6.2.561, but the more recent the better.

Important

From what I can tell by testing it out, it does not work with the online server version of RStudio. I could not get it to download the booktem package and I am not sure how well it works with github, so you will need a local installation.

1.2.1 Installing Base R

Install base R. Choose the download link for your operating system (Linux, Mac OS X, or Windows).

If you have a Mac, install the latest release from the newest R-x.x.x.pkg link (or a legacy version if you have an older operating system). After you install R, you should also install XQuartz to be able to use some visualisation packages.

If you are installing the Windows version, choose the “base” subdirectory and click on the download link at the top of the page. After you install R, you should also install RTools and use the “recommended” version highlighted near the top of the list.

If you are using Linux, choose your specific operating system and follow the installation instructions. If you use Linux, you probably do not need help from me for installing software and I will probably not know how to help you as I have never used Linux.

1.2.2 Installing RStudio

Go to rstudio.com and download the RStudio Desktop version for your operating system. It should recognise your operating system and allow you to download via the blue Download button, but you can look for previous versions if you need one.

1.2.3 Install the booktem R package

The PsyTeachR book template is contained within a package hosted on Lisa’s github called booktem. To install the package, run the following code in the Console of RStudio:

devtools::install_github("debruine/booktem")

If you are new to R/RStudio, you probably have no user packages installed, so you will get a prompt to allow booktem to install the other R packages it depends on to work. This might take a few minutes, so go and enjoy yourself a hot drink.

Caution

One of these messages might say something like “do you want to compile packages where there is a binary version” and give you several options to select. You will only be able to select 1 if you have Rtools downloaded on a Windows computer as you need developer tools to do this. Macs should not need any additional software to compile binary packages. These binary versions are normally a little more recent, so its useful to install them if possible.

If you are a more experienced R/RStudio user, you might be prompted to update your R packages that booktem depends on. Obviously use your judgement if you are in a place to update your packages, but the book template might not work with older packages.

1.3 Download git and github desktop

Potentially the most unfamiliar element of this process will be working with git and github. If you have not used it before, git is a version control system which tracks file changes on your computer (like OneDrive but for code). github is an online system which uses git to host those changes and make your code available online. There is a graphical user interface called github desktop which I use and will demonstrate. If you want to use the command line version of git/github, you probably do not need me to show you how.

There is an installation guide on github, but we have access to a fantastic resource developed by our colleagues in Mathematics and Statistics. They developed an accessible online course on Moodle introducing staff and students to version control using git and github. You will need the enrollment code git_psych_24 to access the course. If you use it, please consider completing their feedback form on the Moodle page so they can improve the resource in future.

There are 7 units in total which do not take very long, but for the purposes of this workshop, I would consider 1 and 2 as essential for downloading git/github desktop and using it as a single user to track changes. Reaching this point will be super helpful for following along in the workshop as the terms will be more familiar to you like repositories, commits, and pushing changes.

If you have time, completing unit 3 will give you everything you need if you are only using it on your own. If you plan on writing the book in a team, units 4 and 5 cover being a group project user, then 6 and 7 for advanced features.

Apply for education membership

The standard version of github should meet all your needs, but by working at a university you are eligible to apply for an education membership. If you are interested you can find out more on the github education site for teachers. For example, with an education profile, you can get unlimited private repositories.

1.4 Finished

You are ready to make a book in the workshop! See you all on the 1st of August.