Frequently Asked Questions

Work In Progress

As this is a FAQ, it will continue to grow as we update it. If you have any questions please submit them to the Workbench GitHub discussion forum.

I will attempt to divide these questions up by major categories, but these may shift around as questions come in.

If you have a question about definitions, consult our glossary

Authoring

These FAQs are intended for those who contribute to, maintain, or create lessons using The Workbench. If you only ever visit the website, then head over to the Teaching or Learning sections.

Do I really need to use RStudio?

No. We recommend using RStudio for several reasons that pertain to ease of use and standardisation across systems, but we do not absolutely require it. If you are able to get Git, R, and pandoc installed on your system, then you do not need to use RStudio.

What is an R Library?

An R library is a folder on your computer that stores R packages. When you install R packages, the first message you will see will probably be something like (on Windows):

Installing packages into ‘c:/Users/USER/Documents/R/win-library/4.0’
(as ‘lib’ is unspecified)

This folder is where all of the R packages you install via install.packages() will live. If you ever need to look this up, you can use the .libPaths() function.

Sometimes, your R session will issue a warning that says a folder is not writeable and asks if you would like to use a personal library instead. In this case, select “yes”.

Local Clones

How do I update my clone after the transition from styles?

The easiest way is to rename your local clone to old-NAME (where NAME is the name of your repository folder) and then re-clone the lesson. You can find details on updating your local clone on the beta phase page.

GitHub Forks

How do I update my fork after the transition from styles?

Before you read further

This is only applicable if you have created a fork of the lesson before 2023-02-06.

Do not “synchronise” your fork

If you attempt to synchronise your fork from the GitHub interface and create a pull request, that pull request will fail. Instead, follow the instructions below.

The easiest way to do this is to delete your fork and re-clone. The commit history of the lesson has changed and you will be unable to commit until your fork reflects those changes (this is known as the burn it all down strategy):

1. Save your edits on locally or in a scratch space.
2. Delete your fork
3. Create a new fork or use the “edit” button on the page you wish to edit.
4. Apply your changes (NOTE The Workbench uses a different syntax. Here is a Transition Guide from Styles to Workbench for your reference).

Note that if you have a clone, you will need to also delete and re-clone.

Production Forks

If you have a fork of a lesson that you have modified significantly and wish to continue maintaining under The Workbench, contact Zhian Kamvar and he will help you transition your repository.

contributing without deleting

If you contribute directly on the lesson itself using the “edit” button on GitHub, a new branch will be created for you and you can edit on that branch without deleting your fork.

This method is not recommended because it runs the risk that you will accidentally merge histories in your fork.

Teaching

GitHub Forks

How do I create a fork for teaching?

A common pattern for teaching is to create a fork of a lesson, modify it to add or remove specific section. Because the pages on The Workbench are deployed by GitHub actions, there are a couple of extra steps you need to do to enable the pages to load after the transition.

In short, when you fork, to make it easier, you should bring in all branches, enable GitHub pages, and enable GitHub Actions. After that, you will have your lesson website and can teach from it.

You can find the instructions in issue 14 of the Dovetail blog series.

Workshop Websites

How do I add episodes to my workshop website?

Before 2020, instructors were occasionally encouraged to copy the episodes from a lesson into their workshop website to avoid situations where the lesson would change significantly while the workshop was being taught. In short, you can not do this. Instead, you can make a fork of the lesson and link that on your workshop website.

Coming up: versioned lessons

In the future, we will implement lesson versioning where you will be able to select a specific version of a lesson to teach from, so that you can always be sure that the content is stable.

Low-rent versioning with HTMLpreview

The website https://htmlpreview.github.io allows you to display HTML pages hosted on GitHub without needing to set up GitHub pages. If you do not want to fork, but still want a working version you can teach from, you can head to a workbench repository, select the gh-pages branch, select the index.html file and click on copy permalink and paste that into html preview:

For example: this is the workbench documentation as of 2023-02-07: https://htmlpreview.github.io/?https://github.com/carpentries/sandpaper-docs/blob/59651a69e7716c04edaf8f9c1c79abc18ce3e476/index.html

This is a very workable version of the lesson (with some styling differences as the default font could not be loaded).

The only catch is that you have to manually switch to instructor view by the URL: https://htmlpreview.github.io/?https://github.com/carpentries/sandpaper-docs/blob/59651a69e7716c04edaf8f9c1c79abc18ce3e476/instructor/index.html

And there you have a quick version of the lesson.

Learning