Cohort tech setup

1 Overview

Cohort tech setup involves the iterative setup of technical infrastructure for Champions Cohorts. Things described in this section begin after Pre-cohort engagement ends: after dates are set, 1:1 Intro calls are completed, and Cohort welcome email is sent. Some of this information is echoed in Leading Cohort Calls.

Most things are set up in advance of the first Cohort Call, with a few things set up following the first Call (e.g. inviting folks to Slack and coworking sessions). We generate and review Agendas prior to each Cohort Call; they are not created all in advance.

In this page, we give some general information, then describe things in temporal order.

1.1 Documentation update in progress

In June 2022, for the 2022-noaa-sefsc-summer cohort, we started experimenting with organizing Cohort tech setup in a GitHub Project called CohortPlanning, and we began using kyber to automate as much of the work as possible. With the goal of enabling others to help with tech setup, we have begun updating documentation of the processes below. In the meantime, some items may be duplicated or appear out of order.

2 kyber helps automate some setup

If you’re comfortable following instructions in R (or want to try!), we recommend using our kyber R package created by Sean Kross. kyber contains tools for setting up learning cohorts on GitHub, purpose-built for the Openscapes Champions Program. It automates creation of new GitHub repos and agendas in Google Docs for example, using information from the Cohort Registry (described below).

We’ll need to do some configuration to use kyber, so follow the configuration instructions before you need to use it.

Specific kyber functions will be described in more detail where relevant to specific tasks below.

3 Google Workspace

In June 2022 we began moving our work to an Openscapes Google Workspace, starting with the 2022 NOAA SEFSC summer Cohort.

Folder organization

  • OpenscapesMain > OpenscapesChampionsProgram > contains materials for active and completed Cohorts, including 1-on-1’s and specific Cohort Folders.
  • OpenscapesMain > OpenscapesCohortPlanning > contains materials for planning Cohorts, including the Cohort Registry and docs for Mentors Seaside Chats.

Calendar: The OpenscapesCohorts Google Calendar is used for events, like Cohort Calls and Coworking sessions.

Google Meet: We’ll give some tech details below. Breakout room functionality in Google Meet is limited (e.g. participant cannot dynamically choose a room to join; host must manually assign them).

4 Timing and order of tasks

Pre-cohort engagement (the preceding section) ends with a reminder to participants the day before Cohort Call 1. The “Before Call 1” tasks below must be started before that last-minute reminder.

You might notice some redundancy among this list, the GitHub Project, and Cohort Setup Checklist below. We’re capturing how we do things as our processes evolve.

4.1 Before Call 1

  • Create GitHub repo; make it a website
  • Create Cohort Google Folder
  • Create Call 1 Agenda (kyber)
  • Email reminder to participants - day before (see Pre-cohort engagement)
  • Add participants to Cohort Google Folder - day before

4.2 After Call 1

  • Draft Field Notes (TODO add link to doc)
  • Send Digest to participants via email, then copy to new GitHub Issue in Cohort repo (after Call 2, all digests are added as a GitHub Issue only)
  • Invite participants to Slack
  • Create Google Calendar invite for 4 Coworking sessions (after Calls 1-4) in OpenscapesCohorts calendar. Set Google Meet co-hosts. Add participants as guests.

4.3 Before Call 2

  • Host Coworking session
  • Check in with Cohort Mentors
  • Create Agenda for Call 2 (kyber)
  • Set up GitHub Clinic (kyber)

4.4 After subsequent Calls

  • Host Coworking session
  • Create Agenda (kyber)

5 Managing tasks in a GitHub Project

We monitor and manage the many tasks of cohort tech setup in a GitHub Project. The issues for this project live in the Openscapes/cohort-planning repo. As we experiment, our system will evolve. Currently, issues contain checklists of tasks grouped as: Before Cohort Call 1; After Cohort Call 1; Before Cohort Call 2, etc.

These screenshots show two views of the same GitHub Project, as rows or as cards.

GitHub Project rows view

GitHub Project cards view

Clicking on a row (top screenshot) or on a card (bottom screenshot) takes us to details of that item, and opening in a new tab (circled in red below) would bring us to the familiar GitHub Issue view.

GitHub Project issue

6 Cohort setup checklist

The process of setting up a Cohort is detailed in a checklist. We’ve put it here near the beginning to give a picture of all the elements. These include technical setup in our Google Workspace and GitHub organization, and engagement with participants before and after Cohort Calls.

Below the checklist, we outline how and when to carry out each of the steps, and we’ll refer back here to copy-paste it into a Cohort GitHub repository we’ll create.


This issue is to help track the pre-cohort setup, following the [approach-guide](https://openscapes.github.io/approach-guide/champions/pre-cohort-engage.html#planning-document) and focused on the engagement and tech setup after dates are set.

These TODO's are for @jules32 and also will include @stefaniebutland, as well as Ady

## Quicklinks

-   Planning Google Folder ([SEFSC planning](https://drive.google.com/drive/folders/1qZrhgme_tQ0LeXfRutC5YmFaWvO0H6ZJ)), includes Planning Doc that also serves for Seaside Chats and Debriefs
    -   \[LessonPlannning Spreadsheet\]\
-   \[Cohort Folder\] - to share with Champions (a subfolder within planning folder)
    -   \[ParticipantsList\]

## Prep Announcement

-   [ ] draft events page (https://openscapes.github.io/events)
-   [ ] create google form - Ady made and internal spreadsheet
-   [ ] post events page (with linked google form)

## Tech Setup for Cohort

For Cohort Planning Team (Stef, Julie, Ady)

-   [ ] invite co-leads/assists to Google Calendar Cohort Calls
-   [ ] GitHub:
    -   [ ] create GitHub repo for cohort with cohort name: eg github.com/openscapes/2022-noaa-sefsc-summer
    -   [ ] Make it a website: Settings \> Pages \> Source: main, dir: root
    -   [ ] Invite co-leads to GitHub repo with Admin permissions
    -   [ ] Add our Code of Conduct (kyber)
    -   [ ] Write Cohort info on the README (kyber)
    -   *Add Evaluation information upcoming*
    -   [ ] Add co-leads/assists to GitHub repo with maintainer permission
    -   [ ] create Cohort Planning Checklist Issues, tag planning team
-   [ ] Google Folder:
    -   [ ] create Google Folder for participants: `Openscapes_CohortCalls [ 2022-noaa-sefsc-summer ]`
    -   [ ] add co-leads/assists to Google Folder for participants
-   [ ] Data entry:
    -   [ ] Add Participants to database

## Adding Participants (giving access at the right time)

-   [ ] Emails
    -   [ ] draft welcome email
    -   [ ] send welcome email
    -   [ ] send "reminder" email 1 day before, after adding participants to `Openscapes_CohortCalls [ 2022-noaa-sefsc-summer ]`
-   [ ] Google Calendar:
    -   [ ] add participants emails to Google Calendar Invites: Cohort Calls - Do this when you send Welcome Email Email
-   [ ] Google Folder:
    -   [ ] add participants emails to `Openscapes_CohortCalls [ 2022-noaa-sefsc-summer ]` - Do this the day before Cohort Call 1
-   [ ] GitHub:
    -   [ ] ask participants to provide their GitHub usernames - Do this after Cohort Call 1
    -   [ ] add participants to GitHub repo with `kyber` - Do this before GitHub Clinic
    -   [ ] create GitHub Clinic files with `kyber` - Do this before GitHub Clinic
-   [ ] Slack
    -   [ ] Add participant emails to Slack; create cohort channel - Do this after Cohort Call 1
-   [ ] Google Calendar
    -   [ ] add participants emails to Google Calendar Invites: Co-working times (optional) - Do this after Cohort Call 1

7 Cohort Registry

Review the Cohort Registry and update information for the new Cohort. This might be iterative as you create the GitHub repo and Google Drive folder. The Cohort Registry Google Sheet is in suggestion mode and will be used to generate the Cohort Call Agendas using kyber. Particularly important fields for kyber:

  • cohort_name: our convention is year-shortname
  • date_start: in DD/MM/YYYY format
  • github_repo: github repository URL (even if not yet created)
  • google_drive_folder: URL

In 2021 we experimented doing this in the openscapes/cohort-planning repository and also in the Cohort repo itself. In the cohort’s repo it’s one less place for Mentors to keep track of and there is the added benefit of an example issue in the repo for the GitHub Clinic.

If you prefer to make this planning issue in the openscapes/cohort-planning repo, that is great too. Here was our original details: This repo coordinates across cohorts, so it’s best to “unwatch” except when you’re tagged and then we tag each issue with the folks involved. We’re using GitHub teams to group folks involved in each cohort and easily tag them. This way, we can all learn and coordinate across cohorts when we want to poke through the issues but aren’t cluttered with emails. Two starting Issues to make:

  • “Quicklinks” Issue with links nice to have open during Cohort Calls. Example: 2022-nmfs-afsc. We pin this issue so that it shows up at the top of https://github.com/Openscapes/cohort-planning/issues
  • “Pre-cohort setup: Issue with check-boxes aligned with this approach-guide so we know what’s been done. Aligning this Issue with the approach-guide is a work-in-progress. Example: 2022-nmfs-afsc

8 GitHub repo

screenshot of checklist excerpt

Screenshot of checklist excerpt for GitHub repo and Cohort Google Folder tasks

Create a Cohort GitHub repo within the Openscapes GitHub organization. An example repository looks like this: https://github.com/Openscapes/2021-noaa-nmfs. Our convention has been that the repository name is the same as the cohort_name from the Cohort Registry above, example: 2021-noaa-nmfs. To start, a Cohort repo should include a README and a Code of Conduct. This can be done with kyber, as described below, or by hand by copy-pasting a README from another cohort (we did this for the first 8 Champions cohorts!) and Code of Conduct from the Openscapes website repo.

8.1 Create repo w/ kyber

To use kyber, you’ll open RStudio on your computer (instructions). In the RStudio console, install the kyber library (instructions) and follow the configuration instructions. Because kyber is under development, please re-install it each time. Browse the README to see what additional R packages you might need to install.

There’s an example workflow provided to indicate when kyber can be helpful, before or after Cohort Calls.

  • To create the GitHub repository, we can copy the “Create GitHub repo” code block and paste to run in the RStudio console. Yay, repo created! Review the README for any updates you need to make by hand like updating Quicklinks.
  • Now make it a website: Settings > Pages > Source: main, dir: root
  • Add co-leads/assists to GitHub repo with maintainer permission

9 Add checklist to new repo

We can create a “Cohort Setup Checklist” GitHub Issue to help with our planning inside the Cohort GitHub repo that we just created above. The checklist tracks collective TODO’s and has “quick links” that are nice to have handy for planning and when leading Cohort Calls (the ParticipantsList is important for making team breakout rooms!).

To accomplish this, we can copy the Example Cohort Setup Checklist Issue. Click the “copy-to-clipboard” icon in that code block, paste it in a new GitHub issue and it will appear as a functional checklist. Manually update any links that are specific to the Cohort. Tag the planning team in the issue.

Here are examples from past Cohorts:

10 Cohort Google Folder

  • Create a Google Folder (inside OpenscapesMain > OpenscapesChampionsProgram) for participants with the name of the cohort in brackets, e.g. Openscapes_CohortCalls [ 2021-noaa-nmfs ]. The text inside brackets indicates who will have permission to access the folder. For a recent example - the first to use the Openscapes Google Workspace - see Openscapes_CohortCalls [ 2021-noaa-sefsc-summer].
  • Add a PathwayShare folder and the Pathways Spreadsheet. We’ll encourage participants to share their team’s Pathways there.
  • Add co-leads/assists to Google Folder access

10.1 Before Cohort Call 1

We will add participants’ emails to this Google Folder prior to Call 1. We’ll add Agendas here the days before each Cohort Call. The idea is to avoid overloading people with information - give folks access at the right time.

11 Data entry

As teams form, we:

  • Update database with who is in which cohort
  • Google Folder Permission: Add all Cohort emails (note: some participants will provide a gmail address if their university or work email isn’t gmail; add this address as well)

12 Cohort Call Agendas

We do this in the days before each Cohort Call so that we can draw from a set curriculum but also adapt/refine based on what we hear from participants during Cohort Calls, Co-working, Slack, etc.

We recommend using our kyber R package created by Sean Kross. kyber automates Agenda creation that we can then paste into Google Docs and make any further modifications. You can also do this “by hand” by copy-pasting files from other cohorts if you prefer (we did this for the first few Champions cohorts - see Historical aside below for those instructions).

12.1 Create agendas w/ kyber

You’ll do the following:

  • Generate an Agenda markdown file with kyber
  • Knit to html and copy-paste into a Google Doc in your Cohort Google Folder
  • Change fonts/etc and make any additional modifications

You do this from RStudio, within the Cohort repository (example 2022-noaa-afsc). Make sure you pull before starting in case there are any updates you don’t have locally.

Copy the “Agendas” code block, edit Call details and paste in the console. After knitting and pasting the html in a new Google Doc, edit the formatting listed in Julie’s notes.

Getting errors? See troubleshooting documentation.

Blank agendas are in a public Google Folder. Before each Cohort Call, we:

  • Make a copy
  • Save it in the Cohort Google Folder
  • Edit dates, times, add Google Folder links and Zoom links
  • Review and tailor for Cohort and Facilitator (including Land Acknowledgement)

We usually do this before each Cohort Call (as opposed to all at once at the beginning) as a way for us to review/prepare for each Cohort Call and so to reduce confusion for participants.

13 Slack

After the first Cohort Call, we:

  • Create a private Slack channel for the cohort Invite everyone to Slack

14 GitHub Clinics

GitHub Clinics should be part of the Cohort Calls. (In 2021 we experimented with having them as stand-alone events but found that in some Cohorts it was difficult for participants to make extra time outside of the Cohort Call, and it was extra scheduling for everyone.)

We recommend using our kyber R package created by Sean Kross. kyber automates adding participants’ GitHub usernames to the GitHub repo and creates their own file for them to play around in. You can also do this “by hand” at github.com and copy-paste files from other cohorts if you prefer (we did this for the first few Champions cohorts!).

14.1 Prep clinic w/ kyber

Before the GitHub Clinic, we ask people to create a GitHub account and share their username with us - as part of their task following Cohort Call 1.

To prepare for the Clinic, we do the following (with kyber):

  • Add all usernames with member privileges to a GitHub Team titled like 2022-noaa-afsc-cohort
  • Give the Team access to the Cohort repo
  • Create each person’s files

You do this from RStudio, within the Cohort repository (example 2022-noaa-afsc). Make sure you pull before starting in case there are any updates you don’t have locally.

From RStudio, follow kyber Github Clinic instructions. You might need to install some of other R packages called by kyber for this.

14.2 GitHub Clinic overview

GitHub Clinics are part of Cohort Calls, but can additionally be lead as stand-alone 1 hour events. They require at least two team members.

During the Clinic, the Tech Host will make breakout groups, either based on their actual research team or as a random breakout group, depending on whether they attend with their team. We use the Cohort’s ParticipantsList spreadsheet to assist with identifying teams, and we also ask people to rename themselves in Zoom to identify their team.

The Facilitator leads the agenda, and Teacher talks through the slides and screenshares.

Team members can also circulate in the breakout rooms to check in, help, and share.

Preparing for the GitHub Clinic involves:

  • adding participant GitHub usernames to the Cohort’s repo
  • reviewing the slides

Some history: In 2021 we experimented having GitHub Clinics as stand-alone events between Cohort Calls 1 and 2, offering them twice as well as the recording as part of team’s Seaside Chats. In 2022 we’ll re-instate the GitHub Clinic into Cohort Call 2, and increase the number of Cohort Calls to 5.