Merge pull request #67 from Openscapes/tech-github-pm

champions/pre-cohort-tech.qmd

@@ -11,88 +11,15 @@ Most things are set up in advance of the first Cohort Call, with a few things se
 
 In this page, we give some general information, then describe things in temporal order.
 
-### Project management
+### Project management in GitHub
 
-We use the [CohortPlanning GitHub Project](https://github.com/orgs/Openscapes/projects/7) to manage the tasks involved in running Openscapes Champions Cohorts (since June 2022) and have created GitHub Issue Templates a checklist in each template. Have a look at the list of [templates to choose from](https://github.com/Openscapes/cohort-planning/issues/new/choose) to open a new issue, or the [template markdown files](https://github.com/Openscapes/cohort-planning/tree/main/.github/ISSUE_TEMPLATE) that can be edited. These can be used to quickly set up Issues for new Cohorts.
+We use the [CohortPlanning GitHub Project](https://github.com/orgs/Openscapes/projects/7) to monitor and manage the many tasks involved in running Openscapes Champions Cohorts (since June 2022). The issues for this project live in the [Openscapes/cohort-planning](https://github.com/Openscapes/cohort-planning/issues) repo.
 
-### `kyber` helps automate some setup
-
-If you're comfortable following instructions in R (or want to try!), we recommend using our [`kyber` R package](https://github.com/openscapes/kyber) created by [Sean Kross](https://seankross.com/). `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 began using `kyber` in January 2022, starting with the 2022-afsc winter Cohort.
-
-We'll need to do some configuration to use `kyber`, so follow the [configuration instructions](https://openscapes.github.io/kyber/) before you need to use it.
-
-Specific `kyber` functions will be described in more detail where relevant to specific tasks below.
-
-### 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: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 OpenscapesEvents Google Calendar is used for events, like Cohort Calls and Coworking sessions. This may differ for Cohorts that cannot use Google Tools and use MS Teams for example. Add the CohortFolder link to calendar invites; we learned that folks go to Calendars to find the docs for meetings.
-
-There are limits to the number of Guests that can be added to a calendar invite. Google does not provide information on the actual limit number. Our recommended strategy is to add \~80 Guests initially, then add additional blocks of 40 Guests on subsequent days. We learned this for Cross-Cohort Coworking sessions for 4 NOAA NMFS Cohorts in Fall 2022 when we had \~160 potential participants.
-
-::: {.callout-tip collapse="true"}
-## Tip: Click URL to add to your Google Calendar
-
-Sometimes we ask people add an event to their own Google Calendar without being added explicitly as a Guest. To do this, in a Calendar Event \> click the 3 dots \> Publish event \> choose Copy Link to event and share link in Slack or email saying "Click URL to add this to your Google Calendar". We have used this to let people in a Cohort know of an optional impromptu session like drop-in GitHub help, or a screenshare-and-tell for example.
-:::
-
-**Google Meet**: Breakout room functionality in Google Meet is limited (e.g. participant cannot dynamically choose a room to join; host must manually assign them). We prefer to use Zoom when possible.
-
-**Google Spaces**: We have used Google Spaces for within-Cohort communications like Q&A and resource sharing when that is already the strongly-preferred tool for participants e.g. NOAA NMFS Fall 2022 Cohorts. After Cohort completion, the Openscapes team's support moves entirely to Slack.
-
-## Timing and order of tasks
-
-[Pre-cohort engagement](pre-cohort-engage.qmd) (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 complementarity among this list, the [GitHub Project](https://github.com/orgs/Openscapes/projects/7/), the [Leading Cohort Calls](leading-cohort-calls.qmd) section and Cohort Setup Checklist below. We're capturing how we do things as our processes evolve.
-
-### 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](pre-cohort-engage.qmd#day-prior))
--   Add participants to Cohort Google Folder - day before
-
-### After Call 1
-
--   Draft Debrief/Field Notes after every call
--   Send Digest to participants via email in the week following the Cohort Call. Copy Digest to new GitHub Issue in Cohort repo (after GitHub Clinic, 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 OpenscapesEvents calendar. Add participants as guests.
-
-### Before Call 2
-
--   Host Coworking session
--   Check in with Cohort Mentors
--   Create Agenda for Call 2 (`kyber`)
--   Set up GitHub Clinic (`kyber`)
-
-### After Call 2 and subsequent Calls
-
--   Call Digest as GitHub Issue
--   Host Coworking session
--   Create next Agenda (`kyber`)
-
-### Wrap up
-
--   Final Call Digest
--   Invite Cohort to 3-month checkin
--   Add songs to Spotify
--   Write thank you cards; send stickers
--   Blog post
--   Review Approach Guide for updates
--   Review debrief/field notes and incorporate feedback
+There are [GitHub Issue Templates](https://github.com/Openscapes/cohort-planning/issues/new/choose) for most of the tasks. These contain checklists of tasks grouped as: Before Cohort Call 1; After Cohort Call 1; Before Cohort Call 2, etc and can be used to quickly set up Issues for new Cohorts. When opening a new issue, we're presented with a clickable list of templates to choose from. They each open with a draft title, checklist of tasks, and one or more labels and assignees. We edit the draft issue then click Submit new issue.
 
-## Managing tasks in a GitHub Project
+These templates exist in an [ISSUE_TEMPLATE folder](https://github.com/Openscapes/cohort-planning/tree/main/.github/ISSUE_TEMPLATE) as `.md` files that can be edited directly.
 
-We monitor and manage the many tasks of cohort tech setup in a [GitHub Project](https://github.com/orgs/Openscapes/projects/7/). The issues for this project live in the [Openscapes/cohort-planning repo](https://github.com/Openscapes/cohort-planning/issues). 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.
+TODO: in each GitHub Issue Template, link to the Approach Guide section that describes the tasks.
 
 These screenshots show two views of the same GitHub Project, as rows or as cards.
 
@@ -104,14 +31,23 @@ Clicking on a row (top screenshot) or on a card (bottom screenshot) takes us to
 
 ![](images/github-project-issue.png){fig-alt="GitHub Project issue" fig-align="center" width="90%"}
 
-## Cohort setup checklist {#cohort-setup-checklist}
+::: {.callout-note collapse="true"}
+## Historical aside
 
-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.
+Prior to 2022 summer, we used a single (long) Cohort setup checklist in a GitHub issue - a precursor of our use of GitHub Projects - to manage the tasks. This is described here.
 
-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.
+The process of setting up a Cohort is detailed in a checklist. These include technical setup in our Google Workspace and GitHub organization, and engagement with participants before and after Cohort Calls.
 
-::: {.callout-tip collapse="true"}
-## Example Cohort Setup Checklist
+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** below. 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:
+
+-   <https://github.com/Openscapes/2022-noaa-sefsc-summer/issues/1>
+-   <https://github.com/NASA-Openscapes/2022-nasa-champions/issues/1>.
+
+**Example Cohort Setup Checklist**
 
 ``` markdown
 
@@ -173,6 +109,81 @@ For Cohort Planning Team (Stef, Julie, Ady)
 ```
 :::
 
+### `kyber` helps automate some setup
+
+If you're comfortable following instructions in R (or want to try!), we recommend using our [`kyber` R package](https://github.com/openscapes/kyber) created by [Sean Kross](https://seankross.com/). `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 began using `kyber` in January 2022, starting with the 2022-afsc winter Cohort.
+
+We'll need to do some configuration to use `kyber`, so follow the [configuration instructions](https://openscapes.github.io/kyber/) before you need to use it.
+
+Specific `kyber` functions will be described in more detail where relevant to specific tasks below.
+
+### 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: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 OpenscapesEvents Google Calendar is used for events, like Cohort Calls and Coworking sessions. This may differ for Cohorts that cannot use Google Tools and use MS Teams for example. Add the CohortFolder link to calendar invites; we learned that folks go to Calendars to find the docs for meetings.
+
+There are limits to the number of Guests that can be added to a calendar invite. Google does not provide information on the actual limit number. Our recommended strategy is to add \~80 Guests initially, then add additional blocks of 40 Guests on subsequent days. We learned this for Cross-Cohort Coworking sessions for 4 NOAA NMFS Cohorts in Fall 2022 when we had \~160 potential participants.
+
+::: {.callout-tip collapse="true"}
+## Tip: Click URL to add to your Google Calendar
+
+Sometimes we ask people add an event to their own Google Calendar without being added explicitly as a Guest. To do this, in a Calendar Event \> click the 3 dots \> Publish event \> choose Copy Link to event and share link in Slack or email saying "Click URL to add this to your Google Calendar". We have used this to let people in a Cohort know of an optional impromptu session like drop-in GitHub help, or a screenshare-and-tell for example.
+:::
+
+**Google Meet**: Breakout room functionality in Google Meet is limited (e.g. participant cannot dynamically choose a room to join; host must manually assign them). We prefer to use Zoom when possible.
+
+**Google Spaces**: We have used Google Spaces for within-Cohort communications like Q&A and resource sharing when that is already the strongly-preferred tool for participants e.g. NOAA NMFS Fall 2022 Cohorts. After Cohort completion, the Openscapes team's support moves entirely to Slack.
+
+## Timing and order of tasks
+
+[Pre-cohort engagement](pre-cohort-engage.qmd) (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 complementarity among this list, the [GitHub Project](https://github.com/orgs/Openscapes/projects/7/), the [Leading Cohort Calls](leading-cohort-calls.qmd) section and Cohort Setup Checklist below. We're capturing how we do things as our processes evolve.
+
+### 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](pre-cohort-engage.qmd#day-prior))
+-   Add participants to Cohort Google Folder - day before
+
+### After Call 1
+
+-   Draft Debrief/Field Notes after every call
+-   Send Digest to participants via email in the week following the Cohort Call. Copy Digest to new GitHub Issue in Cohort repo (after GitHub Clinic, 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 OpenscapesEvents calendar. Add participants as guests.
+
+### Before Call 2
+
+-   Host Coworking session
+-   Check in with Cohort Mentors
+-   Create Agenda for Call 2 (`kyber`)
+-   Set up GitHub Clinic (`kyber`)
+
+### After Call 2 and subsequent Calls
+
+-   Call Digest as GitHub Issue
+-   Host Coworking session
+-   Create next Agenda (`kyber`)
+
+### Wrap up
+
+-   Final Call Digest
+-   Invite Cohort to 3-month checkin
+-   Add songs to Spotify
+-   Write thank you cards; send stickers
+-   Blog post
+-   Review Approach Guide for updates
+-   Review debrief/field notes and incorporate feedback
+
 ## Cohort Registry
 
 Review the [Cohort Registry](https://docs.google.com/spreadsheets/d/1Ys9KiTXXmZ_laBoCV2QWEm7AcnGSVQaXvm2xpi4XTSc/edit?usp=sharing) 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`:
@@ -217,17 +228,6 @@ There's an example workflow provided to indicate when `kyber` can be helpful, be
 -   Now make it a website: Settings \> Pages \> Source: main, dir: root
 -   Add co-leads/assists to GitHub repo with maintainer permission
 
-## 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](#cohort-setup-checklist). 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:
-
--   <https://github.com/Openscapes/2022-noaa-sefsc-summer/issues/1>
--   <https://github.com/NASA-Openscapes/2022-nasa-champions/issues/1>.
-
 ## 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\].