Re-organize main toctree

- "workshop roles" section is now only roles.
- Split other pages into different tools and practices.
- Pages themselves still need more editing.

Author: rkdarst

README.md

@@ -20,14 +20,13 @@ Notes mechanics <hackmd-mechanics.md>
 ```
 
 ```{toctree}
-:caption: Workshop playbook
+:caption: Workshop roles
 :maxdepth: 1
 
 roles-overview
 team-leaders
 instructors
-co-instructors
-hackmd-helper
+notes-manager
 expert-helpers
 host
 registration-coordinator
@@ -37,27 +36,47 @@ director
 broadcaster
 video-editor
 workshop-organizers
-workshop-playbook
 ```
 
 ```{toctree}
-:caption: Online teaching
+:caption: Instructor tools and practices
 :maxdepth: 1
+
+instructor-intro
+instructor-stream
+livestream-teaching
+team-teaching
+Lesson presentation hints/checklist <presenting.md>
+instructor-tech-setup
+instructor-tech-online
 online
 coderefinery-mooc
-obs
-online-training
 ```
 
 ```{toctree}
-:caption: Lesson contribution
+:caption: Lesson development
 :maxdepth: 1
 
 Lesson design tutorial and reference <lesson-design.md>
 Lesson review checklist <lesson-review.md>
 Lesson contribution guide <lesson-contribution.md>
 ```
 
+```{toctree}
+:caption: Other tools and practices
+:maxdepth: 1
+
+obs
+workshop-checklist
+Workshop basic requirements checklist (in person) <workshop-requirements-inperson.md>
+Workshop administration (reference) <workshop-administration.md>
+indico/index
+Icebreaker question ideas <icebreakers.md>
+video-checking
+video-editing
+online-training
+```
+
 ```{toctree}
 :caption: Misc
 :maxdepth: 1
@@ -66,7 +85,6 @@ Writing technical docs <tech-docs.md>
 meeting-checklist
 workshop-prep-call
 Summary of the book "Teaching Teach Together" <teaching-tech-together.md>
-
 ```
 
 ```{toctree}

broadcaster.rst

@@ -193,7 +193,7 @@ Before each day
     * attendee hackmd: 
     * notes hackmd: 
     * live preview: 
-    * control panel: http://rkd.zgib.net/obs-tablet-remote/#!auto&host=HOST&port=PORT&password=PASSWORD&config=https://raw.githubusercontent.com/coderefinery/obs-config/master/obs-tablet-remote-config.json
+    * control panel:
 
 
 Before each broadcast

co-instructors.md

@@ -1,4 +1,6 @@
-# Co-instructors
+:orphan:
+
+# OLD: Co-instructors
 
 Since we focus on {doc}`team-teaching`, almost everyone is a
 co-instructor.  But this page is focused on *onboarding new
@@ -51,41 +53,6 @@ when the other is talking.
 
 
 
-## Preparing for your first time
-
-```{figure} img/screenshare/s10-kickstart-prompt-log.png
----
-align: right
-figwidth: 50%
----
-
-An example of a beautiful screenshare.  Note the portrait orientation
-(you have half the screen free for notes and HackMD, learners have
-half the screen free to do their own work).  The terminal is
-dark-on-light, a minimal prompt, no other fancy shell distractions,
-there is a shell history visible, and slightly distinct colors between
-the web browser and the terminal.
-```
-
-- There is some generic technical setup for your own computer - make a
-  clean environment that matches learners, make a good prompt, and so
-  on.  See {doc}`instructor-tech-setup` and
-  {doc}`instructor-tech-online`.
-- Watch the [Demo of CodeRefinery livestream teaching
-  ](https://www.youtube.com/watch?v=WjmttAniZX8) (read the
-  description for an explanation).
-- Talk and plan with your co-instructors: decide which model of
-  co-teaching you will give.
-- Plan the material, try to go through all of the exercises and
-  type-along.
-- Do a run-through of the lesson, practicing what each person says.
-  This can be relatively quick (remember, most of the time in an
-  actual lesson is learners doing exercises alone).
-
-  - Also check the technical setup - make sure that it looks good on
-    screen.
-
-
 
 ## Top issues new co-instructors face
 

director.md

@@ -6,13 +6,14 @@ courses, the director also manages the stream scene/audio selection.
 
 
 * Gives introductions and wrap-ups (to the days, sessions, and
-  instructors), or at least ensures they happen.
+  instructors), or at least ensures someone does them.
+  * Ensures the learenrs know all they need to know to take part.
 * Ensures good flow of the course overall
   * Is aware enough of the schedule so that they can decisively adjust
     it when needed.
   * Keeps time, ensures breaks
-  * Actively discusses with the instructors about these practical
-    arrangements (e.g. negotiating best break times)
+  * Actively discusses with and preps the instructors about these
+    practical arrangements (e.g. negotiating best break times)
 * (livestreaming) Flips the livestream scenes when necessary, cues
   instructors.
 
@@ -57,7 +58,7 @@ So, for example:
 - Start the course on the "title card"
 - Switch to gallery view for introduction
 - Switch to screenshare (and adjust PiP size) during teaching
-- Share HackMD during the break and then make PiP size zero
+- Share Notes during the break and then make PiP size zero
 - Repeat for next courses.
 
 The available controls include:
@@ -68,10 +69,13 @@ The available controls include:
     should not normally be adjusted.
 
 - Scene selection: there is a button to select among these scenes
-  - "Title card": graphics used before learners arrive
+  - "Title": graphics used before learners arrive
   - "Gallery": instructors
-  - "Screenshare": capture of the Zoom screenshare
-  - "Hackmd": just what it says
+  - "SS portrait": capture of a portrait
+  - "SS crop": capture of a landscape screenshare, but crop only a
+    portrait view out of it.
+  - "SS landscape": shrink a full landscape screenshare down to share it.
+  - "Notes": just what it says
 
 ```{sidebar} PiP example
 
@@ -88,20 +92,13 @@ overlaid on the HackMD screenshare.
       the Zoom display.
 
 
-## OBS remote control via obs-tablet-remote
+## OBS remote control
 
 The broadcaster will provide you with a URL to go to the remote
 control.  TODO: picture
 
-This is an example (note: it won't work, because you don't have OBS running):
-
-- coderefinery.github.io/obs-tablet-remote/#!auto&host=HOST&port=4444&password=PASSWORD&config=https://raw.githubusercontent.com/coderefinery/obs-config/master/obs-tablet-remote-config.json
-
-
-Go to this URL.  It will prompt you for a password (or the broadcaster
-might add the password to the URL already).  The OBS remote control
-will open with a pre-arranged configuration for your course, with
-buttons corresponding to the controls you see above.
+Go to the URL.  It will allow you to adjust the stream.  Getting
+trained to do this is not documented here yet.
 
 
 

expert-helpers.md

@@ -1,13 +1,15 @@
 # Expert helpers
 
-We mainly have expert helpers for large workshops.
+We mainly have expert helpers for large workshops that have teams.
+Each team has a team leader, and "expert helper" is the name for a
+staff person who goes between rooms helping the team leaders.
 
 * As an expert helper, your main job is to move between different
   groups and make sure that groups are doing well.
 
 * You might be summoned to a group whose helper needs extra help, or
   take the place of a helper if a group doesn't have one.
-  * Watch HackMD/Zulip for this, though requests might come in from
+  * Watch Notes/Zulip for this, though requests might come in from
     other channels, too.
 
 * No one is expected to know everything, but an expert helper should be
@@ -20,7 +22,7 @@ We mainly have expert helpers for large workshops.
     then you can swap to any other room.
 
 * Report an overview of the pulse of the breakout rooms in zulipchat
-  (or hackmd).  Is everyone behind?  People finishing early?  Big
+  (or Notes).  Is everyone behind?  People finishing early?  Big
   differences between them?  Questions which we should bring up in the
   main room?
 
@@ -56,7 +58,7 @@ difficult problem.
   join and catch up with the same rooms (this promotes familiarity).
     - E.g. A rotates between rooms 1-3, B gets rooms 4-7, C gets rooms
       8-11.
-- **Make sure to watch the HackMD for expert helper requests**, this could help
+- **Make sure to watch the Notes for expert helper requests**, this could help
   you decide which room to jump to next.  Comment when you are heading
   there.
 
@@ -66,7 +68,7 @@ Concrete example for an expert helper's time:
   a minute since I am not needed (if there is a good break, I'll ask
   "everything OK?  good, see you around.").  If there are questions
   that I can help with, I answer them.  If they seem to be struggling,
-  then I will make a note in the HackMD and stay a while longer and
+  then I will make a note in the Notes and stay a while longer and
   watch/help.
 
 
@@ -89,5 +91,5 @@ Concrete example for an expert helper's time:
 Other reference:
 
 * {doc}`team-leaders`: important reference
-* {doc}`hackmd-helper`: You may spend a lot of time watching hackmd.
+* {doc}`notes-manager`: You may spend a lot of time watching the Notes.
 

host.md

@@ -1,6 +1,11 @@
-# Host
+# Zoom Host
 
-WARNING: page out of date, this is also split to the director.
+This role exists in Zoom workshops, where there is one person in
+charge of managing Zoom.  It is most important when there are teams in
+breakout rooms - those teams take a lot of time to manage.
+
+WARNING: page out of date, Zoom has been improved so that all co-hosts
+can do many things on this page.
 
 - Make all of other staff and expert helpers co-hosts.
 - Take attendance in spreadsheet, if we do that.
@@ -36,9 +41,9 @@ intend for workshop recordings to be useful to new people learning
 later, but they could be.
 
 - Record the workshop or give permission for others to record.
-  - If you are recording, you can't leave and go to other rooms.
+  - If you are recording, you can't go to other breakout rooms.
   - Perhaps a separate computer could record?
-- spotlight speaker
+- Spotlight the current speaker
 - dual monitor mode?
 - ensure that screen is always being shared?
 - stay in speaker view (not gallery view)
@@ -50,6 +55,9 @@ later, but they could be.
 
 ## Streaming
 
+(Zoom provided a way to do streaming directly from it, but we don't
+use it anymore.)
+
 All of the steps needed to record mean that you can stream, too.  In
 fact, you could look at streaming as a side-effect of recording (or a
 way to record).

instructors.md

@@ -1,6 +1,6 @@
 (instructor)=
 
-# Instructors
+# (Co-)Instructors
 
 Instructors are the ones who "lecture" in the workshops - but of
 course there are many other roles which are helping with the teaching,
@@ -11,17 +11,6 @@ This page links guides on various aspects of being an instructor.
 Join the `#coderefinery-tools-workshop` and `#events` channel in the [coderefinery Zulip chat](https://coderefinery.zulipchat.com) and see what workshops are planned.
 Below a few things that might be of interest if you want to teach with us:
 
-```{toctree}
-:maxdepth: 1
-
-instructor-intro
-instructor-stream
-livestream-teaching
-team-teaching
-Lesson presentation hints/checklist <presenting.md>
-instructor-tech-setup
-instructor-tech-online
-```
 
 ## Responsibilities of an instructor
 
@@ -35,6 +24,32 @@ instructor-tech-online
 - After planning/editing the lesson: Do a dry run (prefereably with someone "new" to the topic)
 
 
+
+## Why co-teaching?
+
+```{figure} img/teach-teaching--screenshot.png
+---
+align: right
+figwidth: 50%
+---
+
+Demo of team teaching.  Two people are speaking, in this case one
+is typing and giving the small point of view, and one is explaining
+the big point of view.
+```
+
+The dream of interactive teaching is hard to achieve: most audiences
+are very quiet and even if someone does speak up, it is a small
+fraction of the audience.  We have found a better way: Build the
+interaction straight in to the course by co-teaching.  Instead of
+trying to have a conversation with students, we have a conversation
+among co-instructors.
+
+Co-teaching provides other benefits, such as easier preparation and
+easier presentation.
+
+
+
 ## From team leader/helper to more
 
 Here is one possible pathway from learner to (whatever else).  This is
@@ -61,3 +76,39 @@ completely outside of this pathway.
 
 Let's emphasize again: this is one pathway, but you should do what you
 want.
+
+
+
+## Preparing for your first time
+
+```{figure} img/screenshare/s10-kickstart-prompt-log.png
+---
+align: right
+figwidth: 50%
+---
+
+An example of a beautiful screenshare.  Note the portrait orientation
+(you have half the screen free for notes and HackMD, learners have
+half the screen free to do their own work).  The terminal is
+dark-on-light, a minimal prompt, no other fancy shell distractions,
+there is a shell history visible, and slightly distinct colors between
+the web browser and the terminal.
+```
+
+- There is some generic technical setup for your own computer - make a
+  clean environment that matches learners, make a good prompt, and so
+  on.  See {doc}`instructor-tech-setup` and
+  {doc}`instructor-tech-online`.
+- Watch the [Demo of CodeRefinery livestream teaching
+  ](https://www.youtube.com/watch?v=WjmttAniZX8) (read the
+  description for an explanation).
+- Talk and plan with your co-instructors: decide which model of
+  co-teaching you will give.
+- Plan the material, try to go through all of the exercises and
+  type-along.
+- Do a run-through of the lesson, practicing what each person says.
+  This can be relatively quick (remember, most of the time in an
+  actual lesson is learners doing exercises alone).
+
+  - Also check the technical setup - make sure that it looks good on
+    screen.