From 1c1a281f791358ea5b73a7e2de24a4f51a34ba52 Mon Sep 17 00:00:00 2001 From: "Zhian N. Kamvar" Date: Thu, 20 Apr 2023 10:37:06 -0700 Subject: [PATCH] [automation] transform lesson to sandpaper --- .editorconfig | 26 ++ .github/workflows/README.md | 198 ++++++++++ .github/workflows/pr-close-signal.yaml | 23 ++ .github/workflows/pr-comment.yaml | 185 +++++++++ .github/workflows/pr-post-remove-branch.yaml | 32 ++ .github/workflows/pr-preflight.yaml | 39 ++ .github/workflows/pr-receive.yaml | 131 +++++++ .github/workflows/sandpaper-main.yaml | 61 +++ .github/workflows/sandpaper-version.txt | 1 + .github/workflows/update-cache.yaml | 125 ++++++ .github/workflows/update-workflows.yaml | 66 ++++ .github/workflows/workbench-beta-phase.yml | 60 +++ .gitignore | 55 +++ CODE_OF_CONDUCT.md | 13 + CONTRIBUTING.md | 121 ++++++ LICENSE.md | 79 ++++ README.md | 24 +- _extras/online-workshop-guidelines.md | 17 - config.yaml | 83 ++++ episodes/01-online-workshops-module-1.md | 310 ++++++++------- episodes/02-online-workshops-module-2.md | 359 ++++++++++-------- {fig => episodes/fig}/ScreenOrganization.png | Bin {fig => episodes/fig}/claim_host.png | Bin index.md | 35 +- .../bonus_module_calendar.md | 14 +- .../instructor-notes.md | 50 ++- instructors/online-workshop-guidelines.md | 24 ++ {_extras => learners}/discuss.md | 5 +- learners/reference.md | 13 + setup.md => learners/setup.md | 6 +- profiles/learner-profiles.md | 5 + reference.md | 9 - site/README.md | 2 + 33 files changed, 1818 insertions(+), 353 deletions(-) create mode 100644 .editorconfig create mode 100755 .github/workflows/README.md create mode 100755 .github/workflows/pr-close-signal.yaml create mode 100755 .github/workflows/pr-comment.yaml create mode 100755 .github/workflows/pr-post-remove-branch.yaml create mode 100755 .github/workflows/pr-preflight.yaml create mode 100755 .github/workflows/pr-receive.yaml create mode 100755 .github/workflows/sandpaper-main.yaml create mode 100644 .github/workflows/sandpaper-version.txt create mode 100755 .github/workflows/update-cache.yaml create mode 100755 .github/workflows/update-workflows.yaml create mode 100644 .github/workflows/workbench-beta-phase.yml create mode 100644 .gitignore create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md create mode 100644 LICENSE.md delete mode 100644 _extras/online-workshop-guidelines.md create mode 100644 config.yaml rename {fig => episodes/fig}/ScreenOrganization.png (100%) rename {fig => episodes/fig}/claim_host.png (100%) rename {_extras => instructors}/bonus_module_calendar.md (85%) rename _extras/guide.md => instructors/instructor-notes.md (82%) create mode 100644 instructors/online-workshop-guidelines.md rename {_extras => learners}/discuss.md (58%) create mode 100644 learners/reference.md rename setup.md => learners/setup.md (64%) create mode 100644 profiles/learner-profiles.md delete mode 100644 reference.md create mode 100644 site/README.md diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..5bf4860 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,26 @@ +root = true + +[*] +charset = utf-8 +insert_final_newline = true +trim_trailing_whitespace = true + +[*.md] +indent_size = 2 +indent_style = space +max_line_length = 100 # Please keep this in sync with bin/lesson_check.py! +trim_trailing_whitespace = false # keep trailing spaces in markdown - 2+ spaces are translated to a hard break (
) + +[*.r] +max_line_length = 80 + +[*.py] +indent_size = 4 +indent_style = space +max_line_length = 79 + +[*.sh] +end_of_line = lf + +[Makefile] +indent_style = tab diff --git a/.github/workflows/README.md b/.github/workflows/README.md new file mode 100755 index 0000000..101967e --- /dev/null +++ b/.github/workflows/README.md @@ -0,0 +1,198 @@ +# Carpentries Workflows + +This directory contains workflows to be used for Lessons using the {sandpaper} +lesson infrastructure. Two of these workflows require R (`sandpaper-main.yaml` +and `pr-recieve.yaml`) and the rest are bots to handle pull request management. + +These workflows will likely change as {sandpaper} evolves, so it is important to +keep them up-to-date. To do this in your lesson you can do the following in your +R console: + +```r +# Install/Update sandpaper +options(repos = c(carpentries = "https://carpentries.r-universe.dev/", + CRAN = "https://cloud.r-project.org")) +install.packages("sandpaper") + +# update the workflows in your lesson +library("sandpaper") +update_github_workflows() +``` + +Inside this folder, you will find a file called `sandpaper-version.txt`, which +will contain a version number for sandpaper. This will be used in the future to +alert you if a workflow update is needed. + +What follows are the descriptions of the workflow files: + +## Deployment + +### 01 Build and Deploy (sandpaper-main.yaml) + +This is the main driver that will only act on the main branch of the repository. +This workflow does the following: + + 1. checks out the lesson + 2. provisions the following resources + - R + - pandoc + - lesson infrastructure (stored in a cache) + - lesson dependencies if needed (stored in a cache) + 3. builds the lesson via `sandpaper:::ci_deploy()` + +#### Caching + +This workflow has two caches; one cache is for the lesson infrastructure and +the other is for the the lesson dependencies if the lesson contains rendered +content. These caches are invalidated by new versions of the infrastructure and +the `renv.lock` file, respectively. If there is a problem with the cache, +manual invaliation is necessary. You will need maintain access to the repository +and you can either go to the actions tab and [click on the caches button to find +and invalidate the failing cache](https://github.blog/changelog/2022-10-20-manage-caches-in-your-actions-workflows-from-web-interface/) +or by setting the `CACHE_VERSION` secret to the current date (which will +invalidate all of the caches). + +## Updates + +### Setup Information + +These workflows run on a schedule and at the maintainer's request. Because they +create pull requests that update workflows/require the downstream actions to run, +they need a special repository/organization secret token called +`SANDPAPER_WORKFLOW` and it must have the `public_repo` and `workflow` scope. + +This can be an individual user token, OR it can be a trusted bot account. If you +have a repository in one of the official Carpentries accounts, then you do not +need to worry about this token being present because the Carpentries Core Team +will take care of supplying this token. + +If you want to use your personal account: you can go to + +to create a token. Once you have created your token, you should copy it to your +clipboard and then go to your repository's settings > secrets > actions and +create or edit the `SANDPAPER_WORKFLOW` secret, pasting in the generated token. + +If you do not specify your token correctly, the runs will not fail and they will +give you instructions to provide the token for your repository. + +### 02 Maintain: Update Workflow Files (update-workflow.yaml) + +The {sandpaper} repository was designed to do as much as possible to separate +the tools from the content. For local builds, this is absolutely true, but +there is a minor issue when it comes to workflow files: they must live inside +the repository. + +This workflow ensures that the workflow files are up-to-date. The way it work is +to download the update-workflows.sh script from GitHub and run it. The script +will do the following: + +1. check the recorded version of sandpaper against the current version on github +2. update the files if there is a difference in versions + +After the files are updated, if there are any changes, they are pushed to a +branch called `update/workflows` and a pull request is created. Maintainers are +encouraged to review the changes and accept the pull request if the outputs +are okay. + +This update is run ~~weekly or~~ on demand. + +### 03 Maintain: Update Pacakge Cache (update-cache.yaml) + +For lessons that have generated content, we use {renv} to ensure that the output +is stable. This is controlled by a single lockfile which documents the packages +needed for the lesson and the version numbers. This workflow is skipped in +lessons that do not have generated content. + +Because the lessons need to remain current with the package ecosystem, it's a +good idea to make sure these packages can be updated periodically. The +update cache workflow will do this by checking for updates, applying them in a +branch called `updates/packages` and creating a pull request with _only the +lockfile changed_. + +From here, the markdown documents will be rebuilt and you can inspect what has +changed based on how the packages have updated. + +## Pull Request and Review Management + +Because our lessons execute code, pull requests are a secruity risk for any +lesson and thus have security measures associted with them. **Do not merge any +pull requests that do not pass checks and do not have bots commented on them.** + +This series of workflows all go together and are described in the following +diagram and the below sections: + +![Graph representation of a pull request](https://carpentries.github.io/sandpaper/articles/img/pr-flow.dot.svg) + +### Pre Flight Pull Request Validation (pr-preflight.yaml) + +This workflow runs every time a pull request is created and its purpose is to +validate that the pull request is okay to run. This means the following things: + +1. The pull request does not contain modified workflow files +2. If the pull request contains modified workflow files, it does not contain + modified content files (such as a situation where @carpentries-bot will + make an automated pull request) +3. The pull request does not contain an invalid commit hash (e.g. from a fork + that was made before a lesson was transitioned from styles to use the + workbench). + +Once the checks are finished, a comment is issued to the pull request, which +will allow maintainers to determine if it is safe to run the +"Receive Pull Request" workflow from new contributors. + +### Recieve Pull Request (pr-recieve.yaml) + +**Note of caution:** This workflow runs arbitrary code by anyone who creates a +pull request. GitHub has safeguarded the token used in this workflow to have no +priviledges in the repository, but we have taken precautions to protect against +spoofing. + +This workflow is triggered with every push to a pull request. If this workflow +is already running and a new push is sent to the pull request, the workflow +running from the previous push will be cancelled and a new workflow run will be +started. + +The first step of this workflow is to check if it is valid (e.g. that no +workflow files have been modified). If there are workflow files that have been +modified, a comment is made that indicates that the workflow is not run. If +both a workflow file and lesson content is modified, an error will occurr. + +The second step (if valid) is to build the generated content from the pull +request. This builds the content and uploads three artifacts: + +1. The pull request number (pr) +2. A summary of changes after the rendering process (diff) +3. The rendered files (build) + +Because this workflow builds generated content, it follows the same general +process as the `sandpaper-main` workflow with the same caching mechanisms. + +The artifacts produced are used by the next workflow. + +### Comment on Pull Request (pr-comment.yaml) + +This workflow is triggered if the `pr-recieve.yaml` workflow is successful. +The steps in this workflow are: + +1. Test if the workflow is valid and comment the validity of the workflow to the + pull request. +2. If it is valid: create an orphan branch with two commits: the current state + of the repository and the proposed changes. +3. If it is valid: update the pull request comment with the summary of changes + +Importantly: if the pull request is invalid, the branch is not created so any +malicious code is not published. + +From here, the maintainer can request changes from the author and eventually +either merge or reject the PR. When this happens, if the PR was valid, the +preview branch needs to be deleted. + +### Send Close PR Signal (pr-close-signal.yaml) + +Triggered any time a pull request is closed. This emits an artifact that is the +pull request number for the next action + +### Remove Pull Request Branch (pr-post-remove-branch.yaml) + +Tiggered by `pr-close-signal.yaml`. This removes the temporary branch associated with +the pull request (if it was created). diff --git a/.github/workflows/pr-close-signal.yaml b/.github/workflows/pr-close-signal.yaml new file mode 100755 index 0000000..9b129d5 --- /dev/null +++ b/.github/workflows/pr-close-signal.yaml @@ -0,0 +1,23 @@ +name: "Bot: Send Close Pull Request Signal" + +on: + pull_request: + types: + [closed] + +jobs: + send-close-signal: + name: "Send closing signal" + runs-on: ubuntu-latest + if: ${{ github.event.action == 'closed' }} + steps: + - name: "Create PRtifact" + run: | + mkdir -p ./pr + printf ${{ github.event.number }} > ./pr/NUM + - name: Upload Diff + uses: actions/upload-artifact@v3 + with: + name: pr + path: ./pr + diff --git a/.github/workflows/pr-comment.yaml b/.github/workflows/pr-comment.yaml new file mode 100755 index 0000000..bb2eb03 --- /dev/null +++ b/.github/workflows/pr-comment.yaml @@ -0,0 +1,185 @@ +name: "Bot: Comment on the Pull Request" + +# read-write repo token +# access to secrets +on: + workflow_run: + workflows: ["Receive Pull Request"] + types: + - completed + +concurrency: + group: pr-${{ github.event.workflow_run.pull_requests[0].number }} + cancel-in-progress: true + + +jobs: + # Pull requests are valid if: + # - they match the sha of the workflow run head commit + # - they are open + # - no .github files were committed + test-pr: + name: "Test if pull request is valid" + runs-on: ubuntu-latest + if: > + github.event.workflow_run.event == 'pull_request' && + github.event.workflow_run.conclusion == 'success' + outputs: + is_valid: ${{ steps.check-pr.outputs.VALID }} + payload: ${{ steps.check-pr.outputs.payload }} + number: ${{ steps.get-pr.outputs.NUM }} + msg: ${{ steps.check-pr.outputs.MSG }} + steps: + - name: 'Download PR artifact' + id: dl + uses: carpentries/actions/download-workflow-artifact@main + with: + run: ${{ github.event.workflow_run.id }} + name: 'pr' + + - name: "Get PR Number" + if: ${{ steps.dl.outputs.success == 'true' }} + id: get-pr + run: | + unzip pr.zip + echo "NUM=$(<./NR)" >> $GITHUB_OUTPUT + + - name: "Fail if PR number was not present" + id: bad-pr + if: ${{ steps.dl.outputs.success != 'true' }} + run: | + echo '::error::A pull request number was not recorded. The pull request that triggered this workflow is likely malicious.' + exit 1 + - name: "Get Invalid Hashes File" + id: hash + run: | + echo "json<> $GITHUB_OUTPUT + - name: "Check PR" + id: check-pr + if: ${{ steps.dl.outputs.success == 'true' }} + uses: carpentries/actions/check-valid-pr@main + with: + pr: ${{ steps.get-pr.outputs.NUM }} + sha: ${{ github.event.workflow_run.head_sha }} + headroom: 3 # if it's within the last three commits, we can keep going, because it's likely rapid-fire + invalid: ${{ fromJSON(steps.hash.outputs.json)[github.repository] }} + fail_on_error: true + + # Create an orphan branch on this repository with two commits + # - the current HEAD of the md-outputs branch + # - the output from running the current HEAD of the pull request through + # the md generator + create-branch: + name: "Create Git Branch" + needs: test-pr + runs-on: ubuntu-latest + if: ${{ needs.test-pr.outputs.is_valid == 'true' }} + env: + NR: ${{ needs.test-pr.outputs.number }} + permissions: + contents: write + steps: + - name: 'Checkout md outputs' + uses: actions/checkout@v3 + with: + ref: md-outputs + path: built + fetch-depth: 1 + + - name: 'Download built markdown' + id: dl + uses: carpentries/actions/download-workflow-artifact@main + with: + run: ${{ github.event.workflow_run.id }} + name: 'built' + + - if: ${{ steps.dl.outputs.success == 'true' }} + run: unzip built.zip + + - name: "Create orphan and push" + if: ${{ steps.dl.outputs.success == 'true' }} + run: | + cd built/ + git config --local user.email "actions@github.com" + git config --local user.name "GitHub Actions" + CURR_HEAD=$(git rev-parse HEAD) + git checkout --orphan md-outputs-PR-${NR} + git add -A + git commit -m "source commit: ${CURR_HEAD}" + ls -A | grep -v '^.git$' | xargs -I _ rm -r '_' + cd .. + unzip -o -d built built.zip + cd built + git add -A + git commit --allow-empty -m "differences for PR #${NR}" + git push -u --force --set-upstream origin md-outputs-PR-${NR} + + # Comment on the Pull Request with a link to the branch and the diff + comment-pr: + name: "Comment on Pull Request" + needs: [test-pr, create-branch] + runs-on: ubuntu-latest + if: ${{ needs.test-pr.outputs.is_valid == 'true' }} + env: + NR: ${{ needs.test-pr.outputs.number }} + permissions: + pull-requests: write + steps: + - name: 'Download comment artifact' + id: dl + uses: carpentries/actions/download-workflow-artifact@main + with: + run: ${{ github.event.workflow_run.id }} + name: 'diff' + + - if: ${{ steps.dl.outputs.success == 'true' }} + run: unzip ${{ github.workspace }}/diff.zip + + - name: "Comment on PR" + id: comment-diff + if: ${{ steps.dl.outputs.success == 'true' }} + uses: carpentries/actions/comment-diff@main + with: + pr: ${{ env.NR }} + path: ${{ github.workspace }}/diff.md + + # Comment if the PR is open and matches the SHA, but the workflow files have + # changed + comment-changed-workflow: + name: "Comment if workflow files have changed" + needs: test-pr + runs-on: ubuntu-latest + if: ${{ always() && needs.test-pr.outputs.is_valid == 'false' }} + env: + NR: ${{ github.event.workflow_run.pull_requests[0].number }} + body: ${{ needs.test-pr.outputs.msg }} + permissions: + pull-requests: write + steps: + - name: 'Check for spoofing' + id: dl + uses: carpentries/actions/download-workflow-artifact@main + with: + run: ${{ github.event.workflow_run.id }} + name: 'built' + + - name: 'Alert if spoofed' + id: spoof + if: ${{ steps.dl.outputs.success == 'true' }} + run: | + echo 'body<> $GITHUB_ENV + echo '' >> $GITHUB_ENV + echo '## :x: DANGER :x:' >> $GITHUB_ENV + echo 'This pull request has modified workflows that created output. Close this now.' >> $GITHUB_ENV + echo '' >> $GITHUB_ENV + echo 'EOF' >> $GITHUB_ENV + + - name: "Comment on PR" + id: comment-diff + uses: carpentries/actions/comment-diff@main + with: + pr: ${{ env.NR }} + body: ${{ env.body }} + diff --git a/.github/workflows/pr-post-remove-branch.yaml b/.github/workflows/pr-post-remove-branch.yaml new file mode 100755 index 0000000..62c2e98 --- /dev/null +++ b/.github/workflows/pr-post-remove-branch.yaml @@ -0,0 +1,32 @@ +name: "Bot: Remove Temporary PR Branch" + +on: + workflow_run: + workflows: ["Bot: Send Close Pull Request Signal"] + types: + - completed + +jobs: + delete: + name: "Delete branch from Pull Request" + runs-on: ubuntu-latest + if: > + github.event.workflow_run.event == 'pull_request' && + github.event.workflow_run.conclusion == 'success' + permissions: + contents: write + steps: + - name: 'Download artifact' + uses: carpentries/actions/download-workflow-artifact@main + with: + run: ${{ github.event.workflow_run.id }} + name: pr + - name: "Get PR Number" + id: get-pr + run: | + unzip pr.zip + echo "NUM=$(<./NUM)" >> $GITHUB_OUTPUT + - name: 'Remove branch' + uses: carpentries/actions/remove-branch@main + with: + pr: ${{ steps.get-pr.outputs.NUM }} diff --git a/.github/workflows/pr-preflight.yaml b/.github/workflows/pr-preflight.yaml new file mode 100755 index 0000000..d0d7420 --- /dev/null +++ b/.github/workflows/pr-preflight.yaml @@ -0,0 +1,39 @@ +name: "Pull Request Preflight Check" + +on: + pull_request_target: + branches: + ["main"] + types: + ["opened", "synchronize", "reopened"] + +jobs: + test-pr: + name: "Test if pull request is valid" + if: ${{ github.event.action != 'closed' }} + runs-on: ubuntu-latest + outputs: + is_valid: ${{ steps.check-pr.outputs.VALID }} + permissions: + pull-requests: write + steps: + - name: "Get Invalid Hashes File" + id: hash + run: | + echo "json<> $GITHUB_OUTPUT + - name: "Check PR" + id: check-pr + uses: carpentries/actions/check-valid-pr@main + with: + pr: ${{ github.event.number }} + invalid: ${{ fromJSON(steps.hash.outputs.json)[github.repository] }} + fail_on_error: true + - name: "Comment result of validation" + id: comment-diff + if: ${{ always() }} + uses: carpentries/actions/comment-diff@main + with: + pr: ${{ github.event.number }} + body: ${{ steps.check-pr.outputs.MSG }} diff --git a/.github/workflows/pr-receive.yaml b/.github/workflows/pr-receive.yaml new file mode 100755 index 0000000..371ef54 --- /dev/null +++ b/.github/workflows/pr-receive.yaml @@ -0,0 +1,131 @@ +name: "Receive Pull Request" + +on: + pull_request: + types: + [opened, synchronize, reopened] + +concurrency: + group: ${{ github.ref }} + cancel-in-progress: true + +jobs: + test-pr: + name: "Record PR number" + if: ${{ github.event.action != 'closed' }} + runs-on: ubuntu-latest + outputs: + is_valid: ${{ steps.check-pr.outputs.VALID }} + steps: + - name: "Record PR number" + id: record + if: ${{ always() }} + run: | + echo ${{ github.event.number }} > ${{ github.workspace }}/NR # 2022-03-02: artifact name fixed to be NR + - name: "Upload PR number" + id: upload + if: ${{ always() }} + uses: actions/upload-artifact@v3 + with: + name: pr + path: ${{ github.workspace }}/NR + - name: "Get Invalid Hashes File" + id: hash + run: | + echo "json<> $GITHUB_OUTPUT + - name: "echo output" + run: | + echo "${{ steps.hash.outputs.json }}" + - name: "Check PR" + id: check-pr + uses: carpentries/actions/check-valid-pr@main + with: + pr: ${{ github.event.number }} + invalid: ${{ fromJSON(steps.hash.outputs.json)[github.repository] }} + + build-md-source: + name: "Build markdown source files if valid" + needs: test-pr + runs-on: ubuntu-latest + if: ${{ needs.test-pr.outputs.is_valid == 'true' }} + env: + GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} + RENV_PATHS_ROOT: ~/.local/share/renv/ + CHIVE: ${{ github.workspace }}/site/chive + PR: ${{ github.workspace }}/site/pr + MD: ${{ github.workspace }}/site/built + steps: + - name: "Check Out Main Branch" + uses: actions/checkout@v3 + + - name: "Check Out Staging Branch" + uses: actions/checkout@v3 + with: + ref: md-outputs + path: ${{ env.MD }} + + - name: "Set up R" + uses: r-lib/actions/setup-r@v2 + with: + use-public-rspm: true + install-r: false + + - name: "Set up Pandoc" + uses: r-lib/actions/setup-pandoc@v2 + + - name: "Setup Lesson Engine" + uses: carpentries/actions/setup-sandpaper@main + with: + cache-version: ${{ secrets.CACHE_VERSION }} + + - name: "Setup Package Cache" + uses: carpentries/actions/setup-lesson-deps@main + with: + cache-version: ${{ secrets.CACHE_VERSION }} + + - name: "Validate and Build Markdown" + id: build-site + run: | + sandpaper::package_cache_trigger(TRUE) + sandpaper::validate_lesson(path = '${{ github.workspace }}') + sandpaper:::build_markdown(path = '${{ github.workspace }}', quiet = FALSE) + shell: Rscript {0} + + - name: "Generate Artifacts" + id: generate-artifacts + run: | + sandpaper:::ci_bundle_pr_artifacts( + repo = '${{ github.repository }}', + pr_number = '${{ github.event.number }}', + path_md = '${{ env.MD }}', + path_pr = '${{ env.PR }}', + path_archive = '${{ env.CHIVE }}', + branch = 'md-outputs' + ) + shell: Rscript {0} + + - name: "Upload PR" + uses: actions/upload-artifact@v3 + with: + name: pr + path: ${{ env.PR }} + + - name: "Upload Diff" + uses: actions/upload-artifact@v3 + with: + name: diff + path: ${{ env.CHIVE }} + retention-days: 1 + + - name: "Upload Build" + uses: actions/upload-artifact@v3 + with: + name: built + path: ${{ env.MD }} + retention-days: 1 + + - name: "Teardown" + run: sandpaper::reset_site() + shell: Rscript {0} diff --git a/.github/workflows/sandpaper-main.yaml b/.github/workflows/sandpaper-main.yaml new file mode 100755 index 0000000..e17707a --- /dev/null +++ b/.github/workflows/sandpaper-main.yaml @@ -0,0 +1,61 @@ +name: "01 Build and Deploy Site" + +on: + push: + branches: + - main + - master + schedule: + - cron: '0 0 * * 2' + workflow_dispatch: + inputs: + name: + description: 'Who triggered this build?' + required: true + default: 'Maintainer (via GitHub)' + reset: + description: 'Reset cached markdown files' + required: false + default: false + type: boolean +jobs: + full-build: + name: "Build Full Site" + runs-on: ubuntu-latest + permissions: + checks: write + contents: write + pages: write + env: + GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} + RENV_PATHS_ROOT: ~/.local/share/renv/ + steps: + + - name: "Checkout Lesson" + uses: actions/checkout@v3 + + - name: "Set up R" + uses: r-lib/actions/setup-r@v2 + with: + use-public-rspm: true + install-r: false + + - name: "Set up Pandoc" + uses: r-lib/actions/setup-pandoc@v2 + + - name: "Setup Lesson Engine" + uses: carpentries/actions/setup-sandpaper@main + with: + cache-version: ${{ secrets.CACHE_VERSION }} + + - name: "Setup Package Cache" + uses: carpentries/actions/setup-lesson-deps@main + with: + cache-version: ${{ secrets.CACHE_VERSION }} + + - name: "Deploy Site" + run: | + reset <- "${{ github.event.inputs.reset }}" == "true" + sandpaper::package_cache_trigger(TRUE) + sandpaper:::ci_deploy(reset = reset) + shell: Rscript {0} diff --git a/.github/workflows/sandpaper-version.txt b/.github/workflows/sandpaper-version.txt new file mode 100644 index 0000000..4aa0906 --- /dev/null +++ b/.github/workflows/sandpaper-version.txt @@ -0,0 +1 @@ +0.11.15 diff --git a/.github/workflows/update-cache.yaml b/.github/workflows/update-cache.yaml new file mode 100755 index 0000000..676d742 --- /dev/null +++ b/.github/workflows/update-cache.yaml @@ -0,0 +1,125 @@ +name: "03 Maintain: Update Package Cache" + +on: + workflow_dispatch: + inputs: + name: + description: 'Who triggered this build (enter github username to tag yourself)?' + required: true + default: 'monthly run' + schedule: + # Run every tuesday + - cron: '0 0 * * 2' + +jobs: + preflight: + name: "Preflight Check" + runs-on: ubuntu-latest + outputs: + ok: ${{ steps.check.outputs.ok }} + steps: + - id: check + run: | + if [[ ${{ github.event_name }} == 'workflow_dispatch' ]]; then + echo "ok=true" >> $GITHUB_OUTPUT + echo "Running on request" + # using single brackets here to avoid 08 being interpreted as octal + # https://github.com/carpentries/sandpaper/issues/250 + elif [ `date +%d` -le 7 ]; then + # If the Tuesday lands in the first week of the month, run it + echo "ok=true" >> $GITHUB_OUTPUT + echo "Running on schedule" + else + echo "ok=false" >> $GITHUB_OUTPUT + echo "Not Running Today" + fi + + check_renv: + name: "Check if We Need {renv}" + runs-on: ubuntu-latest + needs: preflight + if: ${{ needs.preflight.outputs.ok == 'true'}} + outputs: + needed: ${{ steps.renv.outputs.exists }} + steps: + - name: "Checkout Lesson" + uses: actions/checkout@v3 + - id: renv + run: | + if [[ -d renv ]]; then + echo "exists=true" >> $GITHUB_OUTPUT + fi + + check_token: + name: "Check SANDPAPER_WORKFLOW token" + runs-on: ubuntu-latest + needs: check_renv + if: ${{ needs.check_renv.outputs.needed == 'true' }} + outputs: + workflow: ${{ steps.validate.outputs.wf }} + repo: ${{ steps.validate.outputs.repo }} + steps: + - name: "validate token" + id: validate + uses: carpentries/actions/check-valid-credentials@main + with: + token: ${{ secrets.SANDPAPER_WORKFLOW }} + + update_cache: + name: "Update Package Cache" + needs: check_token + if: ${{ needs.check_token.outputs.repo== 'true' }} + runs-on: ubuntu-latest + env: + GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} + RENV_PATHS_ROOT: ~/.local/share/renv/ + steps: + + - name: "Checkout Lesson" + uses: actions/checkout@v3 + + - name: "Set up R" + uses: r-lib/actions/setup-r@v2 + with: + use-public-rspm: true + install-r: false + + - name: "Update {renv} deps and determine if a PR is needed" + id: update + uses: carpentries/actions/update-lockfile@main + with: + cache-version: ${{ secrets.CACHE_VERSION }} + + - name: Create Pull Request + id: cpr + if: ${{ steps.update.outputs.n > 0 }} + uses: carpentries/create-pull-request@main + with: + token: ${{ secrets.SANDPAPER_WORKFLOW }} + delete-branch: true + branch: "update/packages" + commit-message: "[actions] update ${{ steps.update.outputs.n }} packages" + title: "Update ${{ steps.update.outputs.n }} packages" + body: | + :robot: This is an automated build + + This will update ${{ steps.update.outputs.n }} packages in your lesson with the following versions: + + ``` + ${{ steps.update.outputs.report }} + ``` + + :stopwatch: In a few minutes, a comment will appear that will show you how the output has changed based on these updates. + + If you want to inspect these changes locally, you can use the following code to check out a new branch: + + ```bash + git fetch origin update/packages + git checkout update/packages + ``` + + - Auto-generated by [create-pull-request][1] on ${{ steps.update.outputs.date }} + + [1]: https://github.com/carpentries/create-pull-request/tree/main + labels: "type: package cache" + draft: false diff --git a/.github/workflows/update-workflows.yaml b/.github/workflows/update-workflows.yaml new file mode 100755 index 0000000..288bcd1 --- /dev/null +++ b/.github/workflows/update-workflows.yaml @@ -0,0 +1,66 @@ +name: "02 Maintain: Update Workflow Files" + +on: + workflow_dispatch: + inputs: + name: + description: 'Who triggered this build (enter github username to tag yourself)?' + required: true + default: 'weekly run' + clean: + description: 'Workflow files/file extensions to clean (no wildcards, enter "" for none)' + required: false + default: '.yaml' + schedule: + # Run every Tuesday + - cron: '0 0 * * 2' + +jobs: + check_token: + name: "Check SANDPAPER_WORKFLOW token" + runs-on: ubuntu-latest + outputs: + workflow: ${{ steps.validate.outputs.wf }} + repo: ${{ steps.validate.outputs.repo }} + steps: + - name: "validate token" + id: validate + uses: carpentries/actions/check-valid-credentials@main + with: + token: ${{ secrets.SANDPAPER_WORKFLOW }} + + update_workflow: + name: "Update Workflow" + runs-on: ubuntu-latest + needs: check_token + if: ${{ needs.check_token.outputs.workflow == 'true' }} + steps: + - name: "Checkout Repository" + uses: actions/checkout@v3 + + - name: Update Workflows + id: update + uses: carpentries/actions/update-workflows@main + with: + clean: ${{ github.event.inputs.clean }} + + - name: Create Pull Request + id: cpr + if: "${{ steps.update.outputs.new }}" + uses: carpentries/create-pull-request@main + with: + token: ${{ secrets.SANDPAPER_WORKFLOW }} + delete-branch: true + branch: "update/workflows" + commit-message: "[actions] update sandpaper workflow to version ${{ steps.update.outputs.new }}" + title: "Update Workflows to Version ${{ steps.update.outputs.new }}" + body: | + :robot: This is an automated build + + Update Workflows from sandpaper version ${{ steps.update.outputs.old }} -> ${{ steps.update.outputs.new }} + + - Auto-generated by [create-pull-request][1] on ${{ steps.update.outputs.date }} + + [1]: https://github.com/carpentries/create-pull-request/tree/main + labels: "type: template and tools" + draft: false diff --git a/.github/workflows/workbench-beta-phase.yml b/.github/workflows/workbench-beta-phase.yml new file mode 100644 index 0000000..2faa25d --- /dev/null +++ b/.github/workflows/workbench-beta-phase.yml @@ -0,0 +1,60 @@ +name: "Deploy to AWS" + +on: + workflow_run: + workflows: ["01 Build and Deploy Site"] + types: + - completed + workflow_dispatch: + +jobs: + preflight: + name: "Preflight Check" + runs-on: ubuntu-latest + outputs: + ok: ${{ steps.check.outputs.ok }} + folder: ${{ steps.check.outputs.folder }} + steps: + - id: check + run: | + if [[ -z "${{ secrets.DISTRIBUTION }}" || -z "${{ secrets.AWS_ACCESS_KEY_ID }}" || -z "${{ secrets.AWS_SECRET_ACCESS_KEY }}" ]]; then + echo ":information_source: No site configured" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo 'To deploy the preview on AWS, you need the `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` and `DISTRIBUTION` secrets set up' >> $GITHUB_STEP_SUMMARY + else + echo "::set-output name=folder::"$(sed -E 's^.+/(.+)^\1^' <<< ${{ github.repository }}) + echo "::set-output name=ok::true" + fi + + full-build: + name: "Deploy to AWS" + needs: [preflight] + if: ${{ needs.preflight.outputs.ok }} + runs-on: ubuntu-latest + steps: + + - name: "Checkout site folder" + uses: actions/checkout@v3 + with: + ref: 'gh-pages' + path: 'source' + + - name: "Deploy to Bucket" + uses: jakejarvis/s3-sync-action@v0.5.1 + with: + args: --acl public-read --follow-symlinks --delete --exclude '.git/*' + env: + AWS_S3_BUCKET: preview.carpentries.org + AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }} + AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }} + SOURCE_DIR: 'source' + DEST_DIR: ${{ needs.preflight.outputs.folder }} + + - name: "Invalidate CloudFront" + uses: chetan/invalidate-cloudfront-action@master + env: + PATHS: /* + AWS_REGION: 'us-east-1' + DISTRIBUTION: ${{ secrets.DISTRIBUTION }} + AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }} + AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }} diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..b8ab706 --- /dev/null +++ b/.gitignore @@ -0,0 +1,55 @@ +# sandpaper files +episodes/*html +site/* +!site/README.md + +# History files +.Rhistory +.Rapp.history +# Session Data files +.RData +# User-specific files +.Ruserdata +# Example code in package build process +*-Ex.R +# Output files from R CMD build +/*.tar.gz +# Output files from R CMD check +/*.Rcheck/ +# RStudio files +.Rproj.user/ +# produced vignettes +vignettes/*.html +vignettes/*.pdf +# OAuth2 token, see https://github.com/hadley/httr/releases/tag/v0.3 +.httr-oauth +# knitr and R markdown default cache directories +*_cache/ +/cache/ +# Temporary files created by R markdown +*.utf8.md +*.knit.md +# R Environment Variables +.Renviron +# pkgdown site +docs/ +# translation temp files +po/*~ +# renv detritus +renv/sandbox/ +*.pyc +*~ +.DS_Store +.ipynb_checkpoints +.sass-cache +.jekyll-cache/ +.jekyll-metadata +__pycache__ +_site +.Rproj.user +.bundle/ +.vendor/ +vendor/ +.docker-vendor/ +Gemfile.lock +.*history diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..f19b804 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,13 @@ +--- +title: "Contributor Code of Conduct" +--- + +As contributors and maintainers of this project, +we pledge to follow the [The Carpentries Code of Conduct][coc]. + +Instances of abusive, harassing, or otherwise unacceptable behavior +may be reported by following our [reporting guidelines][coc-reporting]. + + +[coc-reporting]: https://docs.carpentries.org/topic_folders/policies/incident-reporting.html +[coc]: https://docs.carpentries.org/topic_folders/policies/code-of-conduct.html diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..ec44704 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,121 @@ +## Contributing + +[The Carpentries][cp-site] ([Software Carpentry][swc-site], [Data +Carpentry][dc-site], and [Library Carpentry][lc-site]) are open source +projects, and we welcome contributions of all kinds: new lessons, fixes to +existing material, bug reports, and reviews of proposed changes are all +welcome. + +### Contributor Agreement + +By contributing, you agree that we may redistribute your work under [our +license](LICENSE.md). In exchange, we will address your issues and/or assess +your change proposal as promptly as we can, and help you become a member of our +community. Everyone involved in [The Carpentries][cp-site] agrees to abide by +our [code of conduct](CODE_OF_CONDUCT.md). + +### How to Contribute + +The easiest way to get started is to file an issue to tell us about a spelling +mistake, some awkward wording, or a factual error. This is a good way to +introduce yourself and to meet some of our community members. + +1. If you do not have a [GitHub][github] account, you can [send us comments by + email][contact]. However, we will be able to respond more quickly if you use + one of the other methods described below. + +2. If you have a [GitHub][github] account, or are willing to [create + one][github-join], but do not know how to use Git, you can report problems + or suggest improvements by [creating an issue][issues]. This allows us to + assign the item to someone and to respond to it in a threaded discussion. + +3. If you are comfortable with Git, and would like to add or change material, + you can submit a pull request (PR). Instructions for doing this are + [included below](#using-github). + +Note: if you want to build the website locally, please refer to [The Workbench +documentation][template-doc]. + +### Where to Contribute + +1. If you wish to change this lesson, add issues and pull requests here. +2. If you wish to change the template used for workshop websites, please refer + to [The Workbench documentation][template-doc]. + + +### What to Contribute + +There are many ways to contribute, from writing new exercises and improving +existing ones to updating or filling in the documentation and submitting [bug +reports][issues] about things that do not work, are not clear, or are missing. +If you are looking for ideas, please see [the list of issues for this +repository][repo], or the issues for [Data Carpentry][dc-issues], [Library +Carpentry][lc-issues], and [Software Carpentry][swc-issues] projects. + +Comments on issues and reviews of pull requests are just as welcome: we are +smarter together than we are on our own. **Reviews from novices and newcomers +are particularly valuable**: it's easy for people who have been using these +lessons for a while to forget how impenetrable some of this material can be, so +fresh eyes are always welcome. + +### What *Not* to Contribute + +Our lessons already contain more material than we can cover in a typical +workshop, so we are usually *not* looking for more concepts or tools to add to +them. As a rule, if you want to introduce a new idea, you must (a) estimate how +long it will take to teach and (b) explain what you would take out to make room +for it. The first encourages contributors to be honest about requirements; the +second, to think hard about priorities. + +We are also not looking for exercises or other material that only run on one +platform. Our workshops typically contain a mixture of Windows, macOS, and +Linux users; in order to be usable, our lessons must run equally well on all +three. + +### Using GitHub + +If you choose to contribute via GitHub, you may want to look at [How to +Contribute to an Open Source Project on GitHub][how-contribute]. In brief, we +use [GitHub flow][github-flow] to manage changes: + +1. Create a new branch in your desktop copy of this repository for each + significant change. +2. Commit the change in that branch. +3. Push that branch to your fork of this repository on GitHub. +4. Submit a pull request from that branch to the [upstream repository][repo]. +5. If you receive feedback, make changes on your desktop and push to your + branch on GitHub: the pull request will update automatically. + +NB: The published copy of the lesson is usually in the `main` branch. + +Each lesson has a team of maintainers who review issues and pull requests or +encourage others to do so. The maintainers are community volunteers, and have +final say over what gets merged into the lesson. + +### Other Resources + +The Carpentries is a global organisation with volunteers and learners all over +the world. We share values of inclusivity and a passion for sharing knowledge, +teaching and learning. There are several ways to connect with The Carpentries +community listed at including via social +media, slack, newsletters, and email lists. You can also [reach us by +email][contact]. + +[repo]: https://example.com/FIXME +[contact]: mailto:team@carpentries.org +[cp-site]: https://carpentries.org/ +[dc-issues]: https://github.com/issues?q=user%3Adatacarpentry +[dc-lessons]: https://datacarpentry.org/lessons/ +[dc-site]: https://datacarpentry.org/ +[discuss-list]: https://lists.software-carpentry.org/listinfo/discuss +[github]: https://github.com +[github-flow]: https://guides.github.com/introduction/flow/ +[github-join]: https://github.com/join +[how-contribute]: https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github +[issues]: https://carpentries.org/help-wanted-issues/ +[lc-issues]: https://github.com/issues?q=user%3ALibraryCarpentry +[swc-issues]: https://github.com/issues?q=user%3Aswcarpentry +[swc-lessons]: https://software-carpentry.org/lessons/ +[swc-site]: https://software-carpentry.org/ +[lc-site]: https://librarycarpentry.org/ +[template-doc]: https://carpentries.github.io/workbench/ diff --git a/LICENSE.md b/LICENSE.md new file mode 100644 index 0000000..7632871 --- /dev/null +++ b/LICENSE.md @@ -0,0 +1,79 @@ +--- +title: "Licenses" +--- + +## Instructional Material + +All Carpentries (Software Carpentry, Data Carpentry, and Library Carpentry) +instructional material is made available under the [Creative Commons +Attribution license][cc-by-human]. The following is a human-readable summary of +(and not a substitute for) the [full legal text of the CC BY 4.0 +license][cc-by-legal]. + +You are free: + +- to **Share**---copy and redistribute the material in any medium or format +- to **Adapt**---remix, transform, and build upon the material + +for any purpose, even commercially. + +The licensor cannot revoke these freedoms as long as you follow the license +terms. + +Under the following terms: + +- **Attribution**---You must give appropriate credit (mentioning that your work + is derived from work that is Copyright (c) The Carpentries and, where + practical, linking to ), provide a [link to the + license][cc-by-human], and indicate if changes were made. You may do so in + any reasonable manner, but not in any way that suggests the licensor endorses + you or your use. + +- **No additional restrictions**---You may not apply legal terms or + technological measures that legally restrict others from doing anything the + license permits. With the understanding that: + +Notices: + +* You do not have to comply with the license for elements of the material in + the public domain or where your use is permitted by an applicable exception + or limitation. +* No warranties are given. The license may not give you all of the permissions + necessary for your intended use. For example, other rights such as publicity, + privacy, or moral rights may limit how you use the material. + +## Software + +Except where otherwise noted, the example programs and other software provided +by The Carpentries are made available under the [OSI][osi]-approved [MIT +license][mit-license]. + +Permission is hereby granted, free of charge, to any person obtaining a copy of +this software and associated documentation files (the "Software"), to deal in +the Software without restriction, including without limitation the rights to +use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies +of the Software, and to permit persons to whom the Software is furnished to do +so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. + +## Trademark + +"The Carpentries", "Software Carpentry", "Data Carpentry", and "Library +Carpentry" and their respective logos are registered trademarks of [Community +Initiatives][ci]. + +[cc-by-human]: https://creativecommons.org/licenses/by/4.0/ +[cc-by-legal]: https://creativecommons.org/licenses/by/4.0/legalcode +[mit-license]: https://opensource.org/licenses/mit-license.html +[ci]: https://communityin.org/ +[osi]: https://opensource.org diff --git a/README.md b/README.md index 060994a..22f8b40 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,13 @@ +> **ATTENTION** This is an experimental test of [The Carpentries Workbench](https://carpentries.github.io/workbench) lesson infrastructure. +> It was automatically converted from the source lesson via [the lesson transition script](https://github.com/carpentries/lesson-transition/). +> +> If anything seems off, please contact Zhian Kamvar [zkamvar@carpentries.org](mailto:zkamvar@carpentries.org) + # FIXME Lesson title [![Create a Slack Account with us](https://img.shields.io/badge/Create_Slack_Account-The_Carpentries-071159.svg)](https://swc-slack-invite.herokuapp.com/) -This repository generates the corresponding lesson website from [The Carpentries](https://carpentries.org/) repertoire of lessons. +This repository generates the corresponding lesson website from [The Carpentries](https://carpentries.org/) repertoire of lessons. ## Contributing @@ -15,19 +20,17 @@ how to write new episodes. Please see the current list of [issues][FIXME] for ideas for contributing to this repository. For making your contribution, we use the GitHub flow, which is -nicely explained in the chapter [Contributing to a Project](http://git-scm.com/book/en/v2/GitHub-Contributing-to-a-Project) in Pro Git +nicely explained in the chapter [Contributing to a Project](https://git-scm.com/book/en/v2/GitHub-Contributing-to-a-Project) in Pro Git by Scott Chacon. -Look for the tag ![good_first_issue](https://img.shields.io/badge/-good%20first%20issue-gold.svg). This indicates that the maintainers will welcome a pull request fixing this issue. - +Look for the tag ![good\_first\_issue](https://img.shields.io/badge/-good%20first%20issue-gold.svg). This indicates that the maintainers will welcome a pull request fixing this issue. ## Maintainer(s) -Current maintainers of this lesson are - -* FIXME -* FIXME -* FIXME +Current maintainers of this lesson are +- FIXME +- FIXME +- FIXME ## Authors @@ -38,3 +41,6 @@ A list of contributors to the lesson can be found in [AUTHORS](AUTHORS) To cite this lesson, please consult with [CITATION](CITATION) [lesson-example]: https://carpentries.github.io/lesson-example + + + diff --git a/_extras/online-workshop-guidelines.md b/_extras/online-workshop-guidelines.md deleted file mode 100644 index 1b6b313..0000000 --- a/_extras/online-workshop-guidelines.md +++ /dev/null @@ -1,17 +0,0 @@ -# Online Workshop Guidelines Organiser -| When? | What? | Concerns | Solution | -|----------------------|----------------------------------------------------|----------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------| -| Pre-workshop | General | So many new things to learn and challenges that are hard to anticipate. | Have plans, document them, and practice your tools. Each platform, even ones you know well, may have difficulties or have unexpected challenges. | -| | Installation | Without direct access to learners’ laptops, working through problems will be more difficult. Home computers may not be able to handle the additional burden of videoconferencing on top of software needed for the lesson itself. | Cloud/web-based options can help work around several of these problems. These provide backup solutions for when installation problems cannot be resolved and may reduce processing loads on computers. The Carpentries will offer some guidance on this, but each locale should review institutional membership options and make their own assessment and recommendations. | -| | Training on new platforms | Many of these communication and conferencing tools will likely be new to learners and instructors. Some methods or features may be new, even if the learner or instructor has used the platform before. | Instructors should create a plan for how each platform will be used, and hold a separate meeting to practice using the tools they plan to use for a workshop. Organizers should also consider scheduling an optional “installation meeting” where learners step through the installation process with live support from the instructors, or host office hours at various times before the workshop and hosted by a variety of helpers so the workload is shared. Some platforms support remote control over a person’s computer, allowing you to type commands and click things. However, the experience can be laggy and jarring and should be used as a last resort. | -| | Adapting to failures | Online tools and connections may go down, be severely impaired, or experience other failures (e.g., permissions problems, etc.). | Develop backup plans and identify alternative platforms identified before instruction begins. These plans mean you can adapt quickly when plans need to change. Ensure that the learners have access to the lesson material, so they can continue to work through things on their own if connections fail or they need to drop out of the call. | -| | Keeping track of operational information | Adding new platforms, procedures, backups, etc. means that it can be hard to keep track of what is the latest guidance. | Intentionally create a place for the most current methods to be documented, but keeping a specific section for “lessons learned” or other notes. As instructors gain experience, these documents should transition into onboarding documentation for new instructors. Store these somewhere centrally accessible for all instructors, and easily findable (especially your backup plans document). | -| When? | What? | Concerns | Solution | -| During the workshop | General | New platforms to remember and new roles and communication behaviours for all. There’s so much extra work to do now, which will take away from instruction time. | Try to keep things simple. When a separate platform may support something extremely well, but your existing tool is just fine, you may want to choose to keep things in a single platform. This may change as your learners and instructors gain more experience, but be mindful about reducing the number of new tools everyone has to use. Remember that your most important learning goals are building people’s confidence and understanding of a tool. Focus on making them feel capable rather than how much material you get through. A confident learner can always go back to the online lessons. Consider recording the instructional sessions and sharing them with learners as a backup, but these are not meant to replace live sessions. | -| | Presenting | Following along with a live coding screen share can be difficult when learners have a single screen. | Take longer breaks and use feedback to get a sense of the room. You’ll have to work a bit harder to ensure that everyone is still on track. | -| | Handling questions | Keeping a queue of questions and tech help requests is difficult and hard to manage as an instructor. | Having a helper dedicated to facilitating questions and problems is key. Even experienced online instructors will find the cognitive load of teaching and managing communications difficult. Instructors and helpers should have a back channel to internally coordinate. | -| | Getting feedback | Minute cards and formative assessment methods don’t translate to these new environments in obvious ways. | Remember that the mechanism of getting feedback isn’t as important as the feedback itself. Things will operate differently, but our priorities of receiving feedback and acting on it haven’t. Other than pre and post workshop surveys, there are many ways to gather this feedback, and The Carpentries will offer some guidance on this. Each locale should develop their own standard methods so that instructors can gain expertise and documentation is consistent. | -| | Distributing resources and operational information | Learners can always ask us if they lose a link, but what if they lose access to us and can’t ask for help? If plans need to change and we don’t have the live or chat sessions to communicate, how can we get everyone back on track? | Communication channels will look different for every group, and your instructor group should put together backup plans that include this sort of information. You may provide an email address, phone number, or WhatsApp contact for people to reach out to in the event of an emergency loss of connection. Have these backup plans documented for the learners, and ask them to save at least one point of contact that doesn’t rely on their computer (e.g. write down a phone number or ensure they have email access on their phone). | -| When? | What? | Concerns | Solution | -| Post-workshop | General | Should post-workshop communication and support look different? | The local instructor group should meet to discuss if anything should change. Many workshops are offered as part of the service portfolio for a research unit, or they are run by independent faculty members. An online workshop may reduce the amount of natural networking opportunities learners would have, so hosting informal chats or meetups may aid in building a community while isolation orders are in effect. | -| | Supporting learners after the workshop | How can we answer questions after a workshop? | Many tools will support this, and the local group should use one that integrates nicely into existing communication channels. This may be a Slack channel for learners, a mailing list, or a Discourse forum. The method doesn’t matter as much as the opportunity to ask questions and have continued support as they learn. diff --git a/config.yaml b/config.yaml new file mode 100644 index 0000000..c28a2f7 --- /dev/null +++ b/config.yaml @@ -0,0 +1,83 @@ +#------------------------------------------------------------ +# Values for this lesson. +#------------------------------------------------------------ + +# Which carpentry is this (swc, dc, lc, or cp)? +# swc: Software Carpentry +# dc: Data Carpentry +# lc: Library Carpentry +# cp: Carpentries (to use for instructor training for instance) +# incubator: The Carpentries Incubator +carpentry: 'cp' + +# Overall title for pages. +title: 'Bonus Modules for Carpentries Instructors' + +# Date the lesson was created (YYYY-MM-DD, this is empty by default) +created: + +# Comma-separated list of keywords for the lesson +keywords: 'software, data, lesson, The Carpentries' + +# Life cycle stage of the lesson +# possible values: pre-alpha, alpha, beta, stable +life_cycle: 'beta' + +# License of the lesson materials (recommended CC-BY 4.0) +license: 'CC-BY 4.0' + +# Link to the source repository for this lesson +source: 'https://github.com/fishtree-attempt/instructor-training-bonus-modules/' + +# Default branch of your lesson +branch: 'main' + +# Who to contact if there are any issues +contact: 'team@carpentries.org' + +# Navigation ------------------------------------------------ +# +# Use the following menu items to specify the order of +# individual pages in each dropdown section. Leave blank to +# include all pages in the folder. +# +# Example ------------- +# +# episodes: +# - introduction.md +# - first-steps.md +# +# learners: +# - setup.md +# +# instructors: +# - instructor-notes.md +# +# profiles: +# - one-learner.md +# - another-learner.md + +# Order of episodes in your lesson +episodes: +- 01-online-workshops-module-1.md +- 02-online-workshops-module-2.md + +# Information for Learners +learners: + +# Information for Instructors +instructors: + +# Learner Profiles +profiles: + +# Customisation --------------------------------------------- +# +# This space below is where custom yaml items (e.g. pinning +# sandpaper and varnish versions) should live + + +url: https://preview.carpentries.org/instructor-training-bonus-modules +analytics: carpentries +lang: en +workbench-beta: 'true' diff --git a/episodes/01-online-workshops-module-1.md b/episodes/01-online-workshops-module-1.md index 8648b20..c833e48 100644 --- a/episodes/01-online-workshops-module-1.md +++ b/episodes/01-online-workshops-module-1.md @@ -1,72 +1,86 @@ --- -title: "Online Workshops Module 1: Know Your Tools" +title: 'Online Workshops Module 1: Know Your Tools' teaching: 50 exercises: 40 -questions: -- "How do you use Zoom host and co-host features?" -- "What do workshop attendees need to know about interacting on Zoom?" -objectives: -- "Use Zoom host and co-host features to create breakouts, screen share, manage muting and more." -- "Create a plan to communicate with learners during a workshop." -keypoints: -- "Hosting features in Zoom are most useful when operated by someone who is not also trying to teach." -- "Communications avenues should be planned and taught for an online workshop to function smoothly." --- -> ## Workshop Roles -> This workshop in intended to be taught by two people. The Discussion Lead should be a Carpentries Instructor Trainer and the Zoom Lead may be a Trainer or Instructor. -> -> Discussion Lead: Introduces the workshop, facilitates icebreakers and discussions of all activities except Activity 0 (using Host powers in Zoom). -> -> Zoom Lead: Assumes (& transfers) "host" role in Zoom, manages breakouts & waiting room, monitors chat, mutes noise, keeps time. Facilitates Activity 0. If you -> wish to demonstrate Zoom captioning, the Zoom Lead can take on this role when participants introduce themselves, since it is not necessary to take notes then. -> -{: .solution} - - - -> ## Workshop Welcome Template (5 min) -> The introductory procedures for this workshop should present an ideal model to attendees. This means paying attention to *all* the details, even though some -> may feel less necessary for a short and small event of this kind. Later activities can then reference practices displayed here. -> -> *Hello! My name is [ name ] and I will be your Discussion Lead for today. As a Carpentries event, this workshop is covered by The Carpentries Code of Conduct. That -> means we will all bring our best selves to support each other in preparing to teach online here today. If you have any concerns you will find links for reporting in the Etherpad. -> -> Before we get started I want to be sure that we all have a plan should anyone lose their -> connection, including me. We will be using the Etherpad to keep notes and links. You will find a link to rejoin this meeting there, as well as links to the -> curriculum. Please be sure you have the Etherpad link available someplace other than our meeting chat. You may be able to send messages there if your call -> drops. If I lose connection, our Zoom Lead, [ name ] will take over. If the call ends, you should be able to reconnect using the information you originally came -> with. Should we have a general failure I will contact folks by email when I can. -> This is a 3 hour workshop with a 15 minute break in the middle. We will take our break at 30 minutes past the next hour regardless of where we are in the curriculum at that time. -> -> The curriculum is primarily for reference outside the workshop, so don't worry about trying to display it or juggling it with your Zoom screen. You may want to -> take a moment to arrange your windows so that you can [see the Etherpad and Zoom at the same time](https://carpentries.github.io/instructor-training-bonus-modules/fig/ScreenOrganization.png). If you prefer to alternate, I will also tell you when we need -> to move between them. If you need any direct assistance during the workshop, you may message [name of Zoom lead] in the chat. Note that you can send private -> messages by selecting someone's name in the dropdown next to the "To:" in the chat window. -> -> In the first exercise, we'll be doing Introductions -- in addition to breaking the ice, we will also be practising one mode of handraising. As we will discuss -> there are many ways to raise hands in Zoom, and you may try them all, but writing "hand" in the chat is the method I'll be paying most attention to today. -> Please open the Etherpad using the link in the chat if you have not already done so, sign in there, and then write "hand" in the chat.* -> -> *(Optional) During your Introductions [name of Zoom lead] will be demonstrating Zoom's manual captioning feature. They will transition to taking notes in the Etherpad after that.* -> -{: .solution} - -> ## Introduce yourself! (10 min) -> In the Etherpad, please sign in with your name, pronouns, and a fun fact about your local area. Note that you can customize your color at the top right. Also, in Zoom, please adjust your name as needed and add pronouns. You can do this by clicking the drop-down to the right of your name in the participants window. -> -> When you are finished, please raise your hand by writing "hand" in the chat. When the Trainer calls on you, unmute and briefly say your name and location (city, country). We'll save the fun facts for your first breakout sessions. -> -{: .challenge} + +::::::::::::::::::::::::::::::::::::::: objectives + +- Use Zoom host and co-host features to create breakouts, screen share, manage muting and more. +- Create a plan to communicate with learners during a workshop. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: questions + +- How do you use Zoom host and co-host features? +- What do workshop attendees need to know about interacting on Zoom? + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +::::::::::::::: solution + +## Workshop Roles + +This workshop in intended to be taught by two people. The Discussion Lead should be a Carpentries Instructor Trainer and the Zoom Lead may be a Trainer or Instructor. + +Discussion Lead: Introduces the workshop, facilitates icebreakers and discussions of all activities except Activity 0 (using Host powers in Zoom). + +Zoom Lead: Assumes (\& transfers) "host" role in Zoom, manages breakouts \& waiting room, monitors chat, mutes noise, keeps time. Facilitates Activity 0. If you +wish to demonstrate Zoom captioning, the Zoom Lead can take on this role when participants introduce themselves, since it is not necessary to take notes then. + +::::::::::::::::::::::::: + +::::::::::::::: solution + +## Workshop Welcome Template (5 min) + +The introductory procedures for this workshop should present an ideal model to attendees. This means paying attention to *all* the details, even though some +may feel less necessary for a short and small event of this kind. Later activities can then reference practices displayed here. + +\*Hello! My name is [ name ] and I will be your Discussion Lead for today. As a Carpentries event, this workshop is covered by The Carpentries Code of Conduct. That +means we will all bring our best selves to support each other in preparing to teach online here today. If you have any concerns you will find links for reporting in the Etherpad. + +Before we get started I want to be sure that we all have a plan should anyone lose their +connection, including me. We will be using the Etherpad to keep notes and links. You will find a link to rejoin this meeting there, as well as links to the +curriculum. Please be sure you have the Etherpad link available someplace other than our meeting chat. You may be able to send messages there if your call +drops. If I lose connection, our Zoom Lead, [ name ] will take over. If the call ends, you should be able to reconnect using the information you originally came +with. Should we have a general failure I will contact folks by email when I can. +This is a 3 hour workshop with a 15 minute break in the middle. We will take our break at 30 minutes past the next hour regardless of where we are in the curriculum at that time. + +The curriculum is primarily for reference outside the workshop, so don't worry about trying to display it or juggling it with your Zoom screen. You may want to +take a moment to arrange your windows so that you can [see the Etherpad and Zoom at the same time](https://carpentries.github.io/instructor-training-bonus-modules/fig/ScreenOrganization.png). If you prefer to alternate, I will also tell you when we need +to move between them. If you need any direct assistance during the workshop, you may message [name of Zoom lead] in the chat. Note that you can send private +messages by selecting someone's name in the dropdown next to the "To:" in the chat window. + +In the first exercise, we'll be doing Introductions -- in addition to breaking the ice, we will also be practising one mode of handraising. As we will discuss +there are many ways to raise hands in Zoom, and you may try them all, but writing "hand" in the chat is the method I'll be paying most attention to today. +Please open the Etherpad using the link in the chat if you have not already done so, sign in there, and then write "hand" in the chat.\* + +*(Optional) During your Introductions [name of Zoom lead] will be demonstrating Zoom's manual captioning feature. They will transition to taking notes in the Etherpad after that.* + +::::::::::::::::::::::::: + +::::::::::::::::::::::::::::::::::::::: challenge + +## Introduce yourself! (10 min) + +In the Etherpad, please sign in with your name, pronouns, and a fun fact about your local area. Note that you can customize your color at the top right. Also, in Zoom, please adjust your name as needed and add pronouns. You can do this by clicking the drop-down to the right of your name in the participants window. + +When you are finished, please raise your hand by writing "hand" in the chat. When the Trainer calls on you, unmute and briefly say your name and location (city, country). We'll save the fun facts for your first breakout sessions. + +:::::::::::::::::::::::::::::::::::::::::::::::::: ## Introduction (5 min) + Prior to 2020, The Carpentries discouraged online workshops. This is because a number of Carpentries teaching practices do not naturally transfer to a video conferencing platform. Among the challenges: -* A video conferencing window occupies **space on a learner’s computer**. -* Learners’ **faces are hidden** which makes it much harder for the instructional team to evaluate how learners are handling the material by observing facial expressions. -* **No sticky notes!** And asking learners to raise their hands in the chat can be confusing. -* **Side conversations** present a challenge. In a video conference it’s not possible to talk quietly in the back of the room while instruction continues. -* **Helpers can’t “drive.”** As much as we recommend against typing on a learner’s machine, this is sometimes necessary for complex problems. Remote control of learner machines is not straightforward. -* **Socialization** doesn’t ‘just happen’. Learners can’t chat with a neighbor or socialise around the snack table during a break. +- A video conferencing window occupies **space on a learner's computer**. +- Learners' **faces are hidden** which makes it much harder for the instructional team to evaluate how learners are handling the material by observing facial expressions. +- **No sticky notes!** And asking learners to raise their hands in the chat can be confusing. +- **Side conversations** present a challenge. In a video conference it's not possible to talk quietly in the back of the room while instruction continues. +- **Helpers can't "drive."** As much as we recommend against typing on a learner's machine, this is sometimes necessary for complex problems. Remote control of learner machines is not straightforward. +- **Socialization** doesn't ‘just happen'. Learners can't chat with a neighbor or socialise around the snack table during a break. We will talk about each of these challenges in the course of this workshop. @@ -76,21 +90,27 @@ After the break, we will come back to talk about *teaching*. Everything you lear Please note that this workshop is intended to supplement, but not to replace The Carpentries [Recommendations for Teaching Carpentries Workshops Online](https://carpentries.org/online-workshop-recommendations/). Be sure to read those recommendations carefully, and check for useful updates each time you teach! - ## How to Host a Workshop: a technical guide (20 min) + The video conferencing platform used by The Carpentries is Zoom. However, your hosting organisation may have another platform. -> ## What platform will you use? -> In the Etherpad, please indicate with an "X" which platform you will be using for your workshop. If you do not see yours listed, please add it. -> - Zoom -> - Jitsi -> - WebEx -> - Skype -> - Blackboard -> - Google Meet or Hangouts -> - Teams -> - Other (please add!) -{: .challenge} +::::::::::::::::::::::::::::::::::::::: challenge + +## What platform will you use? + +In the Etherpad, please indicate with an "X" which platform you will be using for your workshop. If you do not see yours listed, please add it. + +- Zoom +- Jitsi +- WebEx +- Skype +- Blackboard +- Google Meet or Hangouts +- Teams +- Other (please add!) + + +:::::::::::::::::::::::::::::::::::::::::::::::::: We will now spend a little time discussing and demonstrating the host role on Zoom. We will also have an activity that you will rotate through in groups throughout the workshop, where you will have an opportunity to test the host controls. However, if you have questions about other platforms at any point during @@ -98,12 +118,12 @@ the workshop, please ask -- and answer, if you can! -- any questions specific to under your platform name on the Etherpad. Questions that cannot be addressed during the workshop will be directed to our infrastructure team, so be sure to add your email address if you would like us to follow up! - ### Hosting on Zoom + When you enter a Carpentries Zoom room, you will not have host controls. One person on your instructional team will use a "host key" provided in your introductory email to "Claim Host". The button looks like this: -![Screenshot of zoom, with claim host circled in red, indicating how to claim host.]({{ page.root }}/fig/claim_host.png) +![](fig/claim_host.png){alt='Screenshot of zoom, with claim host circled in red, indicating how to claim host.'} Once host has been claimed, you can only become the host when a current host passes that status to you. @@ -112,11 +132,11 @@ As host, you can: - **Pass host or assign a co-host.** [Co-hosts](https://support.zoom.us/hc/en-us/articles/201362603-Host-and-co-host-controls-in-a-meeting) have some of the same privileges as hosts. We recommend that the person teaching use a co-host role, and leaving host powers for someone who has their full attention on managing the meeting. - **Enable and move participants to a waiting room.** This allows you to admit people individually and adds a layer of protection against "zoombombers." The host can -communicate with people in waiting rooms by issuing announcements. People in the waiting -room can not message the host. Take care to press "Admit" if you want to let someone back in -- "Remove" can sound like a good idea but will kick the person out of the meeting, in some cases permanently. + communicate with people in waiting rooms by issuing announcements. People in the waiting + room can not message the host. Take care to press "Admit" if you want to let someone back in -- "Remove" can sound like a good idea but will kick the person out of the meeting, in some cases permanently. - **Mute participants or request they unumute themselves.** In Carpentries rooms, participants are allowed to unmute themselves by default, but this setting can be changed by the -host or co-host if you want or need to enforce muting. + host or co-host if you want or need to enforce muting. - **Turn off (but not on) participants' video.** Rather than turning the video back on, Zoom will send a request to the participant to activate their video. @@ -130,34 +150,38 @@ Zoom updates features frequently, so it is important to expect the unexpected! M but invariably a percentage of attendees will not remember to update. In addition, you may also find that features you were planning to use have changed with new updates. When in doubt, check [the release notes for the latest version](https://support.zoom.us/hc/en-us/sections/201214205-Release-Notes) (or three). +::::::::::::::::::::::::::::::::::::::: challenge + +## Activity Session 0 (to be carried out in parallel with other activities) + +- Group 1 takes turns + - Receiving host status + - Assigning co-host status (to another group member) + - Muting/unmuting another group member + - Sending a participant to the waiting room (a group member who is not co-host) and re-admitting them + - Screensharing (where did all the buttons go?) + - Adjusting who can share their screen + - Managing, messaging, and visiting breakouts (but not creating them) + - Closing the breakout rooms (if you are the last group member to act as host) + - Assigning host to someone else (either to another group member, or if everyone has had a turn as host, back to the instructor) + +The following list may be pasted into the Zoom chat for participants' reference: +Assign a co-host +Mute/unmute +Send group member to waiting room +Share screen +Adjust who can share screen +Breakouts: manage, message, visit +(if last) Close breakouts +Reassign host + -> ## Activity Session 0 (to be carried out in parallel with other activities) -> -> - Group 1 takes turns -> - Receiving host status -> - Assigning co-host status (to another group member) -> - Muting/unmuting another group member -> - Sending a participant to the waiting room (a group member who is not co-host) and re-admitting them -> - Screensharing (where did all the buttons go?) -> - Adjusting who can share their screen -> - Managing, messaging, and visiting breakouts (but not creating them) -> - Closing the breakout rooms (if you are the last group member to act as host) -> - Assigning host to someone else (either to another group member, or if everyone has had a turn as host, back to the instructor) -> -> The following list may be pasted into the Zoom chat for participants' reference: -> Assign a co-host -> Mute/unmute -> Send group member to waiting room -> Share screen -> Adjust who can share screen -> Breakouts: manage, message, visit -> (if last) Close breakouts -> Reassign host -{: .challenge} +:::::::::::::::::::::::::::::::::::::::::::::::::: Since this activity will be carried out during other activities, be aware that people will be playing with the host features for our meeting during your breakout sessions! This will mean someone might enter your breakout room for a visit, or you might see a silly message posted from time to time. If any other strange things happen... please be patient with us! :) ### Resources: + - For more details, see the section on Zoom in [The Carpentries Handbook](https://docs.carpentries.org/topic_folders/communications/tools/zoom_rooms.html?highlight=zoom#information-for-event-hosts). ## Interacting with your Learners Online (40 min) @@ -165,56 +189,76 @@ Since this activity will be carried out during other activities, be aware that p At all Carpentries workshops, we take the quality of our communications seriously. We communicate to inspire, to re-frame errors as opportunities for learning, and, of course, to teach. At an in-person workshop, we communicate with words, with sticky-notes, with smiles and gestures and glances and reassuring presence. Online, most of these communication routes need a new home. In a video conference, only one person can speak at a time. Want to raise your hand? Writing "hand" in the chat as we did above is not the only route, nor is it normally the first thing new users will try. You might: + - wave at the camera (if video is on) - unmute yourself and try to cut in - discover a little hand-like symbol and click it - add your question/comment to the chat instead - freeze, with an acute case of "analysis paralysis" - Then, there is the problem of side conversations. In a video conference, unless you create breakout rooms, all vocal communication is shared with the entire workshop. One natural outlet for these conversations is the chat... but if that is your only outlet, social clutter can make it unusable. We have all had some practice with video meetings by now, and unless you are exceptionally lucky you have had a few experiences that might contribute to your ideas about what *not* to do. During this activity, you will begin by spending about 5 minutes brainstorming with your group to think through some worst-case scenarios for communications between learners and the instructional team, or within the instructional team. -> ## Activity Session 1 (20 min): -> - Groups 2+: -> - Introduce yourselves! -> - Assign group roles: moderator, time keeper, note-taker. Also, designate one person to share a few key points or questions with the class when you return. Plan to rotate these roles as much as possible/practical as we move through the activities today. -> - Consider one of the following scenarios: -> - **Total Eclipse of the Chat:** Instructor is talking and someone (or multiple people) have a question, but the Instructor is not paying attention to the conference chat. -> - **Which Chat?:** A learner asks for help using the Etherpad chat, when all the helpers are watching the Zoom chat. They are stuck for a long time without help. -> - **Banter Blast:** A group of enthusiastic learners uses the Zoom chat for a side conversation about favorite related tools. A request for help gets lost in the noise. -> - **Help the Helper:** A helper engages with a learner and encounters a problem they don't know how to solve. Now the helper needs help and isn't sure how to proceed. -> - **Which Hand?:** You have asked learners to raise hands by writing "hand" in the chat, but one person is waving at the screen, another is using the 'raise hand' button, and neither is being called on by the Instructor. -> - **Breakout Amnesia:** Learners have entered breakout rooms to complete an activity. Once they are there, they realize they do not understand the prompt, but do not know how -> to ask for help. -> - Draft solutions or pre-emptive plans to create a best-case scenario for communications during your workshop. Write some notes in the Etherpad. If you -> have time remaining, consider a second scenario or invent your own. -> -> - Group 1: -> - Introduce yourselves! -> - Complete Activity 0 in cooperation with your Trainer -> - Take note of the role assignment instructions above for your next activity session. -{: .challenge} +::::::::::::::::::::::::::::::::::::::: challenge + +## Activity Session 1 (20 min): + +- Groups 2+: + + - Introduce yourselves! + - Assign group roles: moderator, time keeper, note-taker. Also, designate one person to share a few key points or questions with the class when you return. Plan to rotate these roles as much as possible/practical as we move through the activities today. + - Consider one of the following scenarios: + - **Total Eclipse of the Chat:** Instructor is talking and someone (or multiple people) have a question, but the Instructor is not paying attention to the conference chat. + - **Which Chat?:** A learner asks for help using the Etherpad chat, when all the helpers are watching the Zoom chat. They are stuck for a long time without help. + - **Banter Blast:** A group of enthusiastic learners uses the Zoom chat for a side conversation about favorite related tools. A request for help gets lost in the noise. + - **Help the Helper:** A helper engages with a learner and encounters a problem they don't know how to solve. Now the helper needs help and isn't sure how to proceed. + - **Which Hand?:** You have asked learners to raise hands by writing "hand" in the chat, but one person is waving at the screen, another is using the 'raise hand' button, and neither is being called on by the Instructor. + - **Breakout Amnesia:** Learners have entered breakout rooms to complete an activity. Once they are there, they realize they do not understand the prompt, but do not know how + to ask for help. + - Draft solutions or pre-emptive plans to create a best-case scenario for communications during your workshop. Write some notes in the Etherpad. If you + have time remaining, consider a second scenario or invent your own. + +- Group 1: + + - Introduce yourselves! + - Complete Activity 0 in cooperation with your Trainer + - Take note of the role assignment instructions above for your next activity session. + + +:::::::::::::::::::::::::::::::::::::::::::::::::: Additional resources: [Coderefinery learner's guide to zoom](https://github.com/coderefinery/manuals/blob/master/zoom-mechanics.md) -> ## Keeping Time -> -> There are many ways to keep time during activities, but here are two suggestions that allow everyone to keep track of how much time is left: -> -> - **Zoom Countdown Timer:** Zoom has an option to set a countdown timer for breakout rooms. After creating the breakout rooms, click Options to view additional -> breakout rooms options. Check Set Countdown timer: If this option is checked, the participants will be given a countdown of how much time they have left before -> being returned to the main room. A box can be checked to give you the option of keeping rooms open; otherwise they will automatically close when the timer runs out. -> -> - **[Cuckoo Timer](https://cuckoo.team/):** Cuckoo timer is a website where you can set a timer and share it with other people via a link. -{: .discussion} +:::::::::::::::::::::::::::::::::::::: discussion + +## Keeping Time + +There are many ways to keep time during activities, but here are two suggestions that allow everyone to keep track of how much time is left: + +- **Zoom Countdown Timer:** Zoom has an option to set a countdown timer for breakout rooms. After creating the breakout rooms, click Options to view additional + breakout rooms options. Check Set Countdown timer: If this option is checked, the participants will be given a countdown of how much time they have left before + being returned to the main room. A box can be checked to give you the option of keeping rooms open; otherwise they will automatically close when the timer runs out. + +- **[Cuckoo Timer](https://cuckoo.team/):** Cuckoo timer is a website where you can set a timer and share it with other people via a link. + + +:::::::::::::::::::::::::::::::::::::::::::::::::: ### Debrief (10 min) + Each group should share a few problems and solutions identified during their group conversations. -# BREAK +## BREAK + +:::::::::::::::::::::::::::::::::::::::: keypoints + +- Hosting features in Zoom are most useful when operated by someone who is not also trying to teach. +- Communications avenues should be planned and taught for an online workshop to function smoothly. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + diff --git a/episodes/02-online-workshops-module-2.md b/episodes/02-online-workshops-module-2.md index a03ef95..32e2818 100644 --- a/episodes/02-online-workshops-module-2.md +++ b/episodes/02-online-workshops-module-2.md @@ -1,188 +1,251 @@ --- -title: "Online Workshops Module 2: Making the Dream Work" +title: 'Online Workshops Module 2: Making the Dream Work' teaching: 20 exercises: 55 -questions: -- "What goes into planning an online workshop?" -- "What does an optimal learner experience look like? What can get in the way?" -- "How can I make my workshop maximally inclusive?" -- “What do I do if my learners are unable to install the software?” -objectives: -- "Write and rehearse an introduction to the nuts and bolts of your online workshop." -- "Propose communications strategies for your instructional team." -keypoints: -- "Learners experience many barriers to participation in online workshops. Planning ahead and communicating well will support them in finding a path to success." -- "Effective team work depends on communication." -- “Cloud instances can resolve software installation problems, but also have their own unique limitations.” --- -## Setting the Stage for a Positive Learner Experience (30 min) -In Part 1 of this lesson, we talked about the importance of the right tool at the right time in setting the stage for a motivating, focused workshop experience. -But, there is more to communication than choosing a platform! +::::::::::::::::::::::::::::::::::::::: objectives + +- Write and rehearse an introduction to the nuts and bolts of your online workshop. +- Propose communications strategies for your instructional team. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: questions + +- What goes into planning an online workshop? +- What does an optimal learner experience look like? What can get in the way? +- How can I make my workshop maximally inclusive? +- “What do I do if my learners are unable to install the software?” + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +## Setting the Stage for a Positive Learner Experience (30 min) + +In Part 1 of this lesson, we talked about the importance of the right tool at the right time in setting the stage for a motivating, focused workshop experience. +But, there is more to communication than choosing a platform! ### The Learner Experience: Challenges and Opportunities (5 min) -Online learners are most often joining your workshop from home and will very likely be teaching or helping from home! -'Home' can look very different to different people. Sometimes, features of a home environment can impact participation in an online workshop. Some effects can be positive, but some can create barriers as well! Consider the home +Online learners are most often joining your workshop from home and will very likely be teaching or helping from home! + +'Home' can look very different to different people. Sometimes, features of a home environment can impact participation in an online workshop. Some effects can be positive, but some can create barriers as well! Consider the home enviroment and equipment along with other potential accessibility issues, and plan accommodations wherever possible. -> ## Breaking Down the Learner Experience -> Optimal elements: -> - understands the instructor -> - can keep up with live coding -> - feels comfortable asking for help -> - feels like they 'belong' at the workshop -> - leaves feeling like they can continue to learn skills -> -> Barriers: -> * internet -> * home technology setup (small screen, poor audio/video, installation failures) -> * household distractions (e.g. kids!) -> * 'Zoom fatigue' -> * other accessibility (e.g. need for audio or visual accommodations) -> -> Solutions: -> * Direct learners to curriculum in case they lose connection or need to step away. Follow curriculum. -> * Minimize window-switching and pause to allow learners to juggle screens e.g. when switching to a collaborative document -> * Prepare to use cloud instances if needed, and also provide next steps for after the workshop to learners who use them. -> * Utilize ice-breakers and group activities to help learners feel more comfortable and connect your community -> * Plan for breaks, post the times, and stick to them -> * Consider whether and when to ask learners to turn on their video -> * Where captioning is not an option, assigning a note-taker to directly transcribe -{: .discussion} +:::::::::::::::::::::::::::::::::::::: discussion + +## Breaking Down the Learner Experience + +Optimal elements: + +- understands the instructor +- can keep up with live coding +- feels comfortable asking for help +- feels like they 'belong' at the workshop +- leaves feeling like they can continue to learn skills + +Barriers: + +- internet +- home technology setup (small screen, poor audio/video, installation failures) +- household distractions (e.g. kids!) +- 'Zoom fatigue' +- other accessibility (e.g. need for audio or visual accommodations) + +Solutions: + +- Direct learners to curriculum in case they lose connection or need to step away. Follow curriculum. +- Minimize window-switching and pause to allow learners to juggle screens e.g. when switching to a collaborative document +- Prepare to use cloud instances if needed, and also provide next steps for after the workshop to learners who use them. +- Utilize ice-breakers and group activities to help learners feel more comfortable and connect your community +- Plan for breaks, post the times, and stick to them +- Consider whether and when to ask learners to turn on their video +- Where captioning is not an option, assigning a note-taker to directly transcribe + + +:::::::::::::::::::::::::::::::::::::::::::::::::: ### Getting Off to a Good Start (5 min) -Creating a welcoming environment for your learners starts with teaching them how they can participate in your workshop. + +Creating a welcoming environment for your learners starts with teaching them how they can participate in your workshop. At the beginning of this workshop, your Trainer took several steps to teach you how to participate in *this* workshop. What kinds of things did they do? What else could they have included? -> ## Introduction ingredients -> In addition to introducing the exciting content of your workshop, your learners need to know what to expect and how to behave. This should include: -> - The workshop schedule (including break times) -> - The Code of Conduct -> - The Emergency Plan -> - How to use the technology (e.g., conferencing platform features, chat, collaborative notetaking document) -> - Communication norms (e.g., How to ask questions, how to indicate when you are ok or stuck) -> - How to arrange windows on a single, small laptop screen -> -{: .solution} - -> ## Activity Session 2 (20 min) -> - Rotate group roles: moderator, time keeper, note-taker & sharer. -> - Prepare a short (3 minute) segment of your introduction that will set your learners on a course for success. -> - Rehearse! Give everyone a chance to present first, then exchange feedback, starting with feedback on yourself. Feedback should focus primarily on content, but delivery may be relevant too. Remember to include both targeted praise and constructive feedback. -> - As time allows, share some similarities and differences in introductions within your group in the etherpad. -> - Group 2 completes Activity 0 -{: .challenge} +::::::::::::::: solution + +## Introduction ingredients + +In addition to introducing the exciting content of your workshop, your learners need to know what to expect and how to behave. This should include: + +- The workshop schedule (including break times) +- The Code of Conduct +- The Emergency Plan +- How to use the technology (e.g., conferencing platform features, chat, collaborative notetaking document) +- Communication norms (e.g., How to ask questions, how to indicate when you are ok or stuck) +- How to arrange windows on a single, small laptop screen + +::::::::::::::::::::::::: + +::::::::::::::::::::::::::::::::::::::: challenge + +## Activity Session 2 (20 min) + +- Rotate group roles: moderator, time keeper, note-taker \& sharer. +- Prepare a short (3 minute) segment of your introduction that will set your learners on a course for success. +- Rehearse! Give everyone a chance to present first, then exchange feedback, starting with feedback on yourself. Feedback should focus primarily on content, but delivery may be relevant too. Remember to include both targeted praise and constructive feedback. +- As time allows, share some similarities and differences in introductions within your group in the etherpad. +- Group 2 completes Activity 0 + + +:::::::::::::::::::::::::::::::::::::::::::::::::: ### Debrief (time permiting) + Take a few moments to report back on your experience. What did you learn? What were the challenges? ## Planning Planning Planning (30 minutes) -At this point, you have done quite a bit of work towards planning your workshop. We hope that alone makes your time spent here worthwhile! However, a functioning -workshop demands **teamwork**, and this is especially true in an online setting. For in-person workshops, a workshop can squeak by on -a rough distribution of teaching duties with a quick helper orientation. Online, everyone needs to be on the same page or the workshop is + +At this point, you have done quite a bit of work towards planning your workshop. We hope that alone makes your time spent here worthwhile! However, a functioning +workshop demands **teamwork**, and this is especially true in an online setting. For in-person workshops, a workshop can squeak by on +a rough distribution of teaching duties with a quick helper orientation. Online, everyone needs to be on the same page or the workshop is really at risk. This means that, before your workshop, you will need to bring everyone together. -What makes a good meeting? -> ## Elements of a good meeting -> - A well-structured agenda -> - Meeting roles -> - Notes to record decisions & commitments for future reference -> - Clearly assigned action items -> - Central aims accomplished in allotted time -> -{: .discussion} -In the next activity session, you will work with your group to tease apart the preparation process, separating planning into before- during- and after-the-meeting phases. - -> ## Activity Session 3 (20 min) -> - Rotate group roles: moderator, time keeper, note-taker & sharer. -> - Take a deep breath, then spend a few minutes scanning the [planning checklist in the Recommendations for Teaching Carpentries Workshops Online](https://carpentries.org/online-workshop-recommendations/#planning-your-workshop). -> This checklist is long! BUT, never fear -- you are working as part of a team. Your team can handle it... if you communicate well! -> - Take a few moments to brainstorm the components of a solid team communication strategy. Consider the following questions: -> - How will you communicate before the workshop? -> - Identify one task that can be done asynchronously, and one task that likely requires a meeting -> - How will you communicate during the workshop? -> - What could go wrong with team communications, and how will you troubleshoot? -> -> - Group 3 completes Activity 0 -{: .challenge} +What makes a good meeting? + +:::::::::::::::::::::::::::::::::::::: discussion + +## Elements of a good meeting + +- A well-structured agenda +- Meeting roles +- Notes to record decisions \& commitments for future reference +- Clearly assigned action items +- Central aims accomplished in allotted time + +:::::::::::::::::::::::::::::::::::::::::::::::::: + + +In the next activity session, you will work with your group to tease apart the preparation process, separating planning into before- during- and after-the-meeting phases. + +::::::::::::::::::::::::::::::::::::::: challenge + +## Activity Session 3 (20 min) + +- Rotate group roles: moderator, time keeper, note-taker \& sharer. + +- Take a deep breath, then spend a few minutes scanning the [planning checklist in the Recommendations for Teaching Carpentries Workshops Online](https://carpentries.org/online-workshop-recommendations/#planning-your-workshop). + This checklist is long! BUT, never fear -- you are working as part of a team. Your team can handle it... if you communicate well! + +- Take a few moments to brainstorm the components of a solid team communication strategy. Consider the following questions: + + - How will you communicate before the workshop? + - Identify one task that can be done asynchronously, and one task that likely requires a meeting + - How will you communicate during the workshop? + - What could go wrong with team communications, and how will you troubleshoot? + +- Group 3 completes Activity 0 + + +:::::::::::::::::::::::::::::::::::::::::::::::::: ### Debrief (5 min) + Take a few moments to share some ideas or observations from each group's discussion. Resources: -"[Meetings, Meetings, Meetings](http://teachtogether.tech/#s:meetings)" in _Teaching Tech Together_ by Greg Wilson +"[Meetings, Meetings, Meetings](https://teachtogether.tech/#s:meetings)" in *Teaching Tech Together* by Greg Wilson ## Group Catch-up -> ## Activity Session 4 (15 min) -> - Groups 1-3 should discuss or complete the activity they missed while doing Activity 0. -> When you finish, take a moment to think through what you have learned in this session. What questions -> or concerns do you still have about online training? We may not have time to address them all, but take a moment to add -> notes to the etherpad. -> -> - Group 4 completes Activity 0 -{: .challenge} - -> ## A Few Notes on Cloud Instances (time permitting) -> At Carpentries workshops, we want learners to [use their own machines](https://carpentries.github.io/instructor-training/18-management/#learners-use-their-own-machines) -> as much as possible. This leaves them more prepared to continue learning after the workshops. However, troubleshooting software -> installation problems can be a tremendous challenge even at an in-person event. -> -> In online workshops, the inability to fully view or interact directly with a learner's machine can make difficult problems functionally -> unsolvable. Therefore, The Carpentries now provides [cloud instances for each curriculum](https://github.com/carpentries/scaffolds), pre-loaded with all required software and data. -> These are intended to function as **backups** for learners who are experiencing significant installation difficulties. -> -> There are two main types of cloud instances to be used for Carpentries workshops, each appropriate for different lessons: -> -> - **RStudio Cloud** -> - R-based lessons -> - Git lessons -> - **MyBinder** -> - Python-based lessons -> - Shell lessons (in the absence of R or Git) -> -> RStudio Cloud -> - Requires sign-in -> - Starts up quickly -> - Identical interface to RStudio -> - Saves changes to the learner's own account -> - Does not include nano text editor (must use RStudio text editor) -> -> MyBinder -> - Does not require sign-in -> - Can be slow to load if not used in previous 12 hours -> - Identical interface to Jupyter Hub & Jupyter Lab -> - Does not save to the cloud (must save notebooks and modified data to desktop and re-upload) -> - Session stops after 10 minutes inactivity -> - Non-private session means that login information should not be used. **Do not connect to GitHub from MyBinder.** -> - Has nano text editor installed -> -> If you register your Carpentries workshop with us, you will receive links to backup solutions for your event in a pre-workshop email sent by our workshop coordinators. This email will also -> include information about the caveats discussed above and a link to detailed instructions for learners, including screenshots. We -> recommend that you **only share this information with those learners who have not successfully completed installation on their own -> computer once the workshop has begun.** -> -{: .callout} + +::::::::::::::::::::::::::::::::::::::: challenge + +## Activity Session 4 (15 min) + +- Groups 1-3 should discuss or complete the activity they missed while doing Activity 0. + When you finish, take a moment to think through what you have learned in this session. What questions + or concerns do you still have about online training? We may not have time to address them all, but take a moment to add + notes to the etherpad. + +- Group 4 completes Activity 0 + + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +::::::::::::::::::::::::::::::::::::::::: callout + +## A Few Notes on Cloud Instances (time permitting) + +At Carpentries workshops, we want learners to [use their own machines](https://carpentries.github.io/instructor-training/18-management/#learners-use-their-own-machines) +as much as possible. This leaves them more prepared to continue learning after the workshops. However, troubleshooting software +installation problems can be a tremendous challenge even at an in-person event. + +In online workshops, the inability to fully view or interact directly with a learner's machine can make difficult problems functionally +unsolvable. Therefore, The Carpentries now provides [cloud instances for each curriculum](https://github.com/carpentries/scaffolds), pre-loaded with all required software and data. +These are intended to function as **backups** for learners who are experiencing significant installation difficulties. + +There are two main types of cloud instances to be used for Carpentries workshops, each appropriate for different lessons: + +- **RStudio Cloud** + - R-based lessons + - Git lessons +- **MyBinder** + - Python-based lessons + - Shell lessons (in the absence of R or Git) + +RStudio Cloud + +- Requires sign-in +- Starts up quickly +- Identical interface to RStudio +- Saves changes to the learner's own account +- Does not include nano text editor (must use RStudio text editor) + +MyBinder + +- Does not require sign-in +- Can be slow to load if not used in previous 12 hours +- Identical interface to Jupyter Hub \& Jupyter Lab +- Does not save to the cloud (must save notebooks and modified data to desktop and re-upload) +- Session stops after 10 minutes inactivity +- Non-private session means that login information should not be used. **Do not connect to GitHub from MyBinder.** +- Has nano text editor installed + +If you register your Carpentries workshop with us, you will receive links to backup solutions for your event in a pre-workshop email sent by our workshop coordinators. This email will also +include information about the caveats discussed above and a link to detailed instructions for learners, including screenshots. We +recommend that you **only share this information with those learners who have not successfully completed installation on their own +computer once the workshop has begun.** + +:::::::::::::::::::::::::::::::::::::::::::::::::: ## Wrap-up -The Carpentries community is here to support your work! You may still have questions, and you will almost certainly develop more as you set + +The Carpentries community is here to support your work! You may still have questions, and you will almost certainly develop more as you set about your preparations. What can you do with those questions? -Consider attending a [Community Discussion](https://pad.carpentries.org/community-discussions)! This is a great opportunity to discuss your thoughts and -questions with experienced Carpentries Instructors as well as new trainees eager to learn from your conversation. This is also a great way to share your +Consider attending a [Community Discussion](https://pad.carpentries.org/community-discussions)! This is a great opportunity to discuss your thoughts and +questions with experienced Carpentries Instructors as well as new trainees eager to learn from your conversation. This is also a great way to share your experiences and engage in retrospective analysis after your workshop is complete. - -If you have questions about organizing your online workshop, you can also contact team@carpentries.org for assistance. + +If you have questions about organizing your online workshop, you can also contact [team@carpentries.org](mailto:team@carpentries.org) for assistance. After your workshop, please also consider whether our Recommendations and the content of this Bonus module have served you well. If you would like to suggest -changes to either, please file an Issue in the [GitHub repository for this lesson](https://github.com/carpentries/instructor-training-bonus-modules/issues), or -email your suggestions to team@carpentries.org. +changes to either, please file an Issue in the [GitHub repository for this lesson](https://github.com/carpentries/instructor-training-bonus-modules/issues), or +email your suggestions to [team@carpentries.org](mailto:team@carpentries.org). -We would also really like to have your feedback now! If this module has helped you to feel more prepared, or if you think there are things we could improve, we -would really appreciate hearing about this in our post-workshop survey. Please take a moment to share your feedback with us so that we can continue to +We would also really like to have your feedback now! If this module has helped you to feel more prepared, or if you think there are things we could improve, we +would really appreciate hearing about this in our post-workshop survey. Please take a moment to share your feedback with us so that we can continue to improve our program! -{% include links.md %} -{% include links.md %} + + + +:::::::::::::::::::::::::::::::::::::::: keypoints + +- Learners experience many barriers to participation in online workshops. Planning ahead and communicating well will support them in finding a path to success. +- Effective team work depends on communication. +- “Cloud instances can resolve software installation problems, but also have their own unique limitations.” + +:::::::::::::::::::::::::::::::::::::::::::::::::: + + diff --git a/fig/ScreenOrganization.png b/episodes/fig/ScreenOrganization.png similarity index 100% rename from fig/ScreenOrganization.png rename to episodes/fig/ScreenOrganization.png diff --git a/fig/claim_host.png b/episodes/fig/claim_host.png similarity index 100% rename from fig/claim_host.png rename to episodes/fig/claim_host.png diff --git a/index.md b/index.md index e94025a..91fd0b2 100644 --- a/index.md +++ b/index.md @@ -1,20 +1,31 @@ --- -layout: lesson -root: . # Is the only page that doesn't follow the pattern /:path/index.html -permalink: index.html # Is the only page that doesn't follow the pattern /:path/index.html +permalink: index.html +site: sandpaper::sandpaper_site --- -This repository contains short lessons intended to provide continuing education opportunities for Carpentries Instructors. -Episodes that are intended to be taught together in a single workshop are labeled "Part 1", "Part 2" etc. and should not be -taught separately. + +> **ATTENTION** This is an experimental test of [The Carpentries Workbench](https://carpentries.github.io/workbench) lesson infrastructure. +> It was automatically converted from the source lesson via [the lesson transition script](https://github.com/carpentries/lesson-transition/). +> +> If anything seems off, please contact Zhian Kamvar [zkamvar@carpentries.org](mailto:zkamvar@carpentries.org) + +This repository contains short lessons intended to provide continuing education opportunities for Carpentries Instructors. +Episodes that are intended to be taught together in a single workshop are labeled "Part 1", "Part 2" etc. and should not be +taught separately. {% comment %} This is a comment in Liquid {% endcomment %} -> ## Prerequisites -> -> These lessons assume that all attendees have previously attended a Carpentries Instructor Training workshop. There are no -> software installation requirements or prior readings necessary for these modules. -{: .prereq} +:::::::::::::::::::::::::::::::::::::::::: prereq + +## Prerequisites + +These lessons assume that all attendees have previously attended a Carpentries Instructor Training workshop. There are no +software installation requirements or prior readings necessary for these modules. + + +:::::::::::::::::::::::::::::::::::::::::::::::::: + + + -{% include links.md %} diff --git a/_extras/bonus_module_calendar.md b/instructors/bonus_module_calendar.md similarity index 85% rename from _extras/bonus_module_calendar.md rename to instructors/bonus_module_calendar.md index e5ff49f..72a5e2d 100644 --- a/_extras/bonus_module_calendar.md +++ b/instructors/bonus_module_calendar.md @@ -1,32 +1,32 @@ --- -layout: page -title: "Bonus Module Calendar" +title: Bonus Module Calendar --- # The Carpentries Bonus Module Calendar: 2020-2021 + Introducing The Carpentries first Bonus Module: Teaching Online Are you planning to teach an online Carpentries workshop? Join us for our new Online Teaching Bonus Module for certified Carpentries Instructors! In this **hands-on, interactive 3.5-hour workshop**, you will have an opportunity to: + - Use Zoom host and co-host features to create breakouts, screen share, manage muting and more. - Create and discuss plans to engage with learners during a workshop. -- Write and rehearse an introduction to the logistics of your workshop that prioritizes creating on optimal learner experience and reducing barriers to participation. +- Write and rehearse an introduction to the logistics of your workshop that prioritizes creating on optimal learner experience and reducing barriers to participation. - Propose communications strategies for your instructional team. This session complements but does not replace our Recommendations for Teaching Carpentries Workshops Online. -***Demand for these workshops has been high and space is limited. Please only register if you plan on attending.*** +***Demand for these workshops has been high and space is limited. Please only register if you plan on attending.*** Learn more about this workshop and what to expect here: [Online Teaching Bonus Module Curriculum](https://carpentries.github.io/instructor-training-bonus-modules/) Certified Carpentries Instructors can register for events listed below by clicking on the link for that event and completing the registration through Eventbrite. - This workshop will be hands-on and interactive. ## Events -* November 18, 2021 - *Registration Closed* +- November 18, 2021 - *Registration Closed* -* December 17, 2021 - *Registration Closed* +- December 17, 2021 - *Registration Closed* diff --git a/_extras/guide.md b/instructors/instructor-notes.md similarity index 82% rename from _extras/guide.md rename to instructors/instructor-notes.md index 045ebd6..bafb613 100644 --- a/_extras/guide.md +++ b/instructors/instructor-notes.md @@ -1,54 +1,74 @@ --- -title: "Instructor Notes" +title: Instructor Notes --- + ## Outline from ITB Online Teaching Onboarding: -Etherpad template: [https://pad.carpentries.org/ITTB_online_template](https://pad.carpentries.org/ITTB_online_template) +Etherpad template: [https://pad.carpentries.org/ITTB\_online\_template](https://pad.carpentries.org/ITTB_online_template) + ### Challenges faced by Instructors + - pacing: more important than ever to go slowly; also harder than ever because online moves slower - communication: feedback indicates that Instructors leave uncertain about whether they successfully engaged learners. Have to work harder to hear from learners online. - class size: many groups have been ignoring our advice on keeping online workshops small. There is often institutional pressure to do so. We'd like them to resist! - slow workshops and anxiety over quality probably both contribute to low response rates on post-assessment. We really want Instructors to find time to distribute surveys before sending people away. -Work in progress -- as always but especially with new materials, contributions invited! + Work in progress -- as always but especially with new materials, contributions invited! + ### Overall structure: + - Breaks: designed for 1 x 15 min, can try 3 x 5 min but keep to time - "Activity 0" = Zoom hosting - If you have any groups of 4, 4th group members need to be moved during Activity 0 because time doesn't allow for 4. They can complete Activity 0 during the 4th session (see table below) - some participants don't feel the need to participate (Zoom experts) -- it's good to ask about this first to give them a chance to opt out + #### Group assignments -Group assignments for activity # during each time period are as follows: -| Activity session | Group 1 | Group 2 | Group3 | Group 4 | -|------------------|---------|---------|--------|---------| -| 1 | 0 | 1 | 1 | 1 | -| 2 | 2 | 0 | 2 | 2 | -| 3 | 3 | 3 | 0 | 3 | -| 4 (catch-up) | 1 | 2 | 3 | 0 | +Group assignments for activity # during each time period are as follows: + +| Activity session | Group 1 | Group 2 | Group3 | Group 4 | +| ---------------- | ------- | ------- | ------ | ------- | +| 1 | 0 | 1 | 1 | 1 | +| 2 | 2 | 0 | 2 | 2 | +| 3 | 3 | 3 | 0 | 3 | +| 4 (catch-up) | 1 | 2 | 3 | 0 | - ### Workshop roles + - Discussion Lead (Trainer) - Zoom Lead (Trainer or Instructor) + ### Modeling introductions -Timing is (of course) tight + +Timing is (of course) tight + - if you have 4 groups, you *must* preserve time for all 4 activities. - Content between activities can be more or less interactive, depending on time - Zoom questions in the initial overview can be punted to Activity 0? (Maybe handled in etherpad then?) - Cloud instance material is optional + ### Activity 1 overview + - Purpose is to think through technical aspects of communications online and identify potential failure points, solutions - Challenging to find time to debrief, but important. Making sure they report in the etherpad during breakouts helps to debrief quickly if need be. + ### Activity 2 overview + - Purpose is to prepare participants to empathize with learner experience, then orient towards introducing a workshop in a way that will support those learners. - The activity itself isn't particularly well-matched to the introductory text. Maybe could be a different activity in the future. But feedback indicates that it's fine and people enjoy the practice introducing their online workshop here. - Group roles require a reminder. - Minimal debrief time is ok here -- better to spend that time in the lead-up thinking about learner challenges. + ### Activity 3 overview -- Purpose is to prepare Instructors for the additional planning load and team coherence necessary to make a good online workshop function. + +- Purpose is to prepare Instructors for the additional planning load and team coherence necessary to make a good online workshop function. - It refers them to the planning checklist, which can be overwhelming, but we want them to know about it and figure out how to cope with that now. -- Activity has been updated to ask them to find single examples of things that can be planned asychronously, require a meeting etc. +- Activity has been updated to ask them to find single examples of things that can be planned asychronously, require a meeting etc. - Unlikely to have time to debrief. + ### Assessment + - We will distribute pre and post survey links to participants. We would appreciate it if Zoom Lead could paste the post-survey link into the chat at the end of the workshop. -{% include links.md %} + + + diff --git a/instructors/online-workshop-guidelines.md b/instructors/online-workshop-guidelines.md new file mode 100644 index 0000000..f4ee1d8 --- /dev/null +++ b/instructors/online-workshop-guidelines.md @@ -0,0 +1,24 @@ +--- +~ +--- + +# Online Workshop Guidelines Organiser + +| When? | What? | Concerns | Solution | +| ------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Pre-workshop | General | So many new things to learn and challenges that are hard to anticipate. | Have plans, document them, and practice your tools. Each platform, even ones you know well, may have difficulties or have unexpected challenges. | +| | Installation | Without direct access to learners' laptops, working through problems will be more difficult. Home computers may not be able to handle the additional burden of videoconferencing on top of software needed for the lesson itself. | Cloud/web-based options can help work around several of these problems. These provide backup solutions for when installation problems cannot be resolved and may reduce processing loads on computers. The Carpentries will offer some guidance on this, but each locale should review institutional membership options and make their own assessment and recommendations. | +| | Training on new platforms | Many of these communication and conferencing tools will likely be new to learners and instructors. Some methods or features may be new, even if the learner or instructor has used the platform before. | Instructors should create a plan for how each platform will be used, and hold a separate meeting to practice using the tools they plan to use for a workshop. Organizers should also consider scheduling an optional "installation meeting" where learners step through the installation process with live support from the instructors, or host office hours at various times before the workshop and hosted by a variety of helpers so the workload is shared. Some platforms support remote control over a person's computer, allowing you to type commands and click things. However, the experience can be laggy and jarring and should be used as a last resort. | +| | Adapting to failures | Online tools and connections may go down, be severely impaired, or experience other failures (e.g., permissions problems, etc.). | Develop backup plans and identify alternative platforms identified before instruction begins. These plans mean you can adapt quickly when plans need to change. Ensure that the learners have access to the lesson material, so they can continue to work through things on their own if connections fail or they need to drop out of the call. | +| | Keeping track of operational information | Adding new platforms, procedures, backups, etc. means that it can be hard to keep track of what is the latest guidance. | Intentionally create a place for the most current methods to be documented, but keeping a specific section for "lessons learned" or other notes. As instructors gain experience, these documents should transition into onboarding documentation for new instructors. Store these somewhere centrally accessible for all instructors, and easily findable (especially your backup plans document). | +| When? | What? | Concerns | Solution | +| During the workshop | General | New platforms to remember and new roles and communication behaviours for all. There's so much extra work to do now, which will take away from instruction time. | Try to keep things simple. When a separate platform may support something extremely well, but your existing tool is just fine, you may want to choose to keep things in a single platform. This may change as your learners and instructors gain more experience, but be mindful about reducing the number of new tools everyone has to use. Remember that your most important learning goals are building people's confidence and understanding of a tool. Focus on making them feel capable rather than how much material you get through. A confident learner can always go back to the online lessons. Consider recording the instructional sessions and sharing them with learners as a backup, but these are not meant to replace live sessions. | +| | Presenting | Following along with a live coding screen share can be difficult when learners have a single screen. | Take longer breaks and use feedback to get a sense of the room. You'll have to work a bit harder to ensure that everyone is still on track. | +| | Handling questions | Keeping a queue of questions and tech help requests is difficult and hard to manage as an instructor. | Having a helper dedicated to facilitating questions and problems is key. Even experienced online instructors will find the cognitive load of teaching and managing communications difficult. Instructors and helpers should have a back channel to internally coordinate. | +| | Getting feedback | Minute cards and formative assessment methods don't translate to these new environments in obvious ways. | Remember that the mechanism of getting feedback isn't as important as the feedback itself. Things will operate differently, but our priorities of receiving feedback and acting on it haven't. Other than pre and post workshop surveys, there are many ways to gather this feedback, and The Carpentries will offer some guidance on this. Each locale should develop their own standard methods so that instructors can gain expertise and documentation is consistent. | +| | Distributing resources and operational information | Learners can always ask us if they lose a link, but what if they lose access to us and can't ask for help? If plans need to change and we don't have the live or chat sessions to communicate, how can we get everyone back on track? | Communication channels will look different for every group, and your instructor group should put together backup plans that include this sort of information. You may provide an email address, phone number, or WhatsApp contact for people to reach out to in the event of an emergency loss of connection. Have these backup plans documented for the learners, and ask them to save at least one point of contact that doesn't rely on their computer (e.g. write down a phone number or ensure they have email access on their phone). | +| When? | What? | Concerns | Solution | +| Post-workshop | General | Should post-workshop communication and support look different? | The local instructor group should meet to discuss if anything should change. Many workshops are offered as part of the service portfolio for a research unit, or they are run by independent faculty members. An online workshop may reduce the amount of natural networking opportunities learners would have, so hosting informal chats or meetups may aid in building a community while isolation orders are in effect. | +| | Supporting learners after the workshop | How can we answer questions after a workshop? | Many tools will support this, and the local group should use one that integrates nicely into existing communication channels. This may be a Slack channel for learners, a mailing list, or a Discourse forum. The method doesn't matter as much as the opportunity to ask questions and have continued support as they learn. | + + diff --git a/_extras/discuss.md b/learners/discuss.md similarity index 58% rename from _extras/discuss.md rename to learners/discuss.md index bfc33c5..515e3ba 100644 --- a/_extras/discuss.md +++ b/learners/discuss.md @@ -1,6 +1,9 @@ --- title: Discussion --- + FIXME -{% include links.md %} + + + diff --git a/learners/reference.md b/learners/reference.md new file mode 100644 index 0000000..fa847f8 --- /dev/null +++ b/learners/reference.md @@ -0,0 +1,13 @@ +--- +title: 'FIXME' +--- + +## Glossary + +## Glossary + +FIXME + + + + diff --git a/setup.md b/learners/setup.md similarity index 64% rename from setup.md rename to learners/setup.md index 5802b66..c0fe25c 100644 --- a/setup.md +++ b/learners/setup.md @@ -2,6 +2,8 @@ title: Setup --- -There are no required pre-readings or software to install in advance of these lessons. +There are no required pre-readings or software to install in advance of these lessons. + + + -{% include links.md %} diff --git a/profiles/learner-profiles.md b/profiles/learner-profiles.md new file mode 100644 index 0000000..434e335 --- /dev/null +++ b/profiles/learner-profiles.md @@ -0,0 +1,5 @@ +--- +title: FIXME +--- + +This is a placeholder file. Please add content here. diff --git a/reference.md b/reference.md deleted file mode 100644 index 8c82616..0000000 --- a/reference.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -layout: reference ---- - -## Glossary - -FIXME - -{% include links.md %} diff --git a/site/README.md b/site/README.md new file mode 100644 index 0000000..42997e3 --- /dev/null +++ b/site/README.md @@ -0,0 +1,2 @@ +This directory contains rendered lesson materials. Please do not edit files +here.