forked from carpentries/workbench
-
Notifications
You must be signed in to change notification settings - Fork 0
/
faq.qmd
224 lines (148 loc) · 8.75 KB
/
faq.qmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
---
title: 'Frequently Asked Questions'
date: '2023-03-29'
---
::: {.callout-caution}
## 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](https://github.com/carpentries/workbench/discussions).
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](reference.html#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](#teaching) or [Learning](#learning) sections.
### Why was R chosen for the infrastructure? {#why-r}
Most tools for webpage authoring outside of Wordpress and the like expect
authors to have some knowledge or ability to manipulate HTML, CSS, JavaScript
and one (or two) other languages to wrangle them all together. It's great for
people who are dabbling in webpage development, but as we've seen for several
years now, it's not great for people who do not have much experience with these
technologies (think about the last time you assisted someone to install Jekyll
correctly).
We chose R for four main reasons:
1. It has a really robust publishing ecosystem
2. It is available as a binary application on all major platforms with a
packaging system that more often than not just works
3. Most of all: The R community as a whole is vibrant, diverse, welcoming, and
is most aligned with The Carpentries core values.
4. It provides a throughline between the tools we teach and real-world
applications.
We tested the infrastructure in 2021 to make sure that it works for people with
varying levels of familiarity with R:
See this [Blog Post from 2021 on the Alpha Test of the infrastructure](https://carpentries.org/blog/2021/07/infrastructure-testing/).
Zhian Kamvar has given two talks about The Workbench that go into a little bit
more detail about why we chose R (which highlight the points above)
| Talk | Video | Slides (with speaker notes) |
| --- | ---- | ----------- |
| [Using R as a Community Workbench for The Carpentries Lesson Infrastructure](https://zkamvar.netlify.app/talk/carpentries-user-2021/) | [Use!R 2021 Video](https://youtu.be/vd8XZSuY_Rs?t=1240 "Zhian's talk from Use!R in 2021") | <https://zkamvar.github.io/user2021/#p1> |
| [Building Accessible Lessons with R and Friends](https://zkamvar.netlify.app/talk/carpentries-rstudio-2022/) | [`rstudio::conf(2022)` Video](https://www.rstudio.com/conference/2022/talks/building-accessible-lessons-r-friends/?wvideo=ssot3tfv28 "Zhian's talk from RStudio in 2021") | <https://zkamvar.github.io/rstudio-conf-2022/#p1> |
### Do I really need to use RStudio? {#do-i-need-rstudio}
No. We recommend using RStudio for [several reasons that pertain to ease of
use and standardisation across systems](#recommend), 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? {#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? {#update-clone-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](beta-phase.html#updating-clone) on the
beta phase page.
### GitHub Forks
#### How do I update my fork after the transition from styles? {#update-fork-from-styles}
::: {.callout-important}
##### Before you read further
**This is only applicable if you have created a fork of the lesson before
2023-02-06.**
:::
::: {.callout-important}
##### 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](https://happygitwithr.com/burn.html)):
1. Save your edits on locally or in a scratch space.
2. **[Delete your fork](https://docs.github.com/en/repositories/creating-and-managing-repositories/deleting-a-repository)**
3. **[Create a new fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo)** 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](https://carpentries.github.io/workbench/transition-guide.html)
for your reference).
Note that if you have a clone, you will need to also [delete and re-clone](#update-clone-from-styles).
<iframe width="100%" height="315" src="https://www.youtube-nocookie.com/embed/9DVwy818MIE" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
::: {.callout-note}
##### 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.
:::
::: {.callout-warning}
##### 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? {#teaching-fork}
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](https://carpentries.org/blog/2023/01/dovetail-14/#tips-and-tricks-for-using-the-workbench).
### 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](#teaching-fork) and link
that on your workshop website.
::: {.callout-note}
##### 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.
:::
::: {.callout-tip}
##### 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