diff --git a/content/screenshare.md b/content/screenshare.md index 364a6c4..b604b42 100644 --- a/content/screenshare.md +++ b/content/screenshare.md @@ -1,20 +1,362 @@ (screenshare)= -# Screenshare +# How to prepare a quality screen-share :::{objectives} -- Be aware of the importance of a well planned screenshare +- Discuss the importance of a well planned screen-share. +- Learn how to prepare and how to test your screen-share setup. +- Know about typical pitfalls and habits to avoid. ::: :::{instructor-note} -- Teaching: ? min -- Exercises: ? min +- Discussion: 25 min +- Exercises: 20 min ::: -Here the episode sections and text ... +## Share portrait layout instead of sharing entire screen when teaching online +- Many learners will have a smaller screen than you. +- You should plan for learners with **only one small screen**. +- A learner will **need to focus on both your screen share and their + work**. +- Share a **portrait**/**vertical half of your screen** (840 × 1080 is our standard and your + maximum). +- Zoom provides a "Share a part of screen" that is good for this. + +:::{figure} screenshare/landscape.png +:width: 80% + +A FullHD 1920x1080 screen shared. Learners have to make this really small if +they want to have something else open. +::: + +:::{figure} screenshare/portrait.png +:width: 45% + +Portrait layout. Allows learners to have something else open in the other half. +::: + +Motivation for portrait layout: +- This makes it easier for you to look at some other notes or to coordinate + with other instructors at the same time + without distracting with too much information. +- This makes it possible for participants to have something else open in the + other screen half: terminal or browser or notebook. + + +### Instructor perspective + +:::{figure} screenshare/instructor.png +:width: 75% + +**I1**: +This is how it can look for the instructor. Zoom is sharing a portion of the left +side, the right side is free for following notes, chat, etc. +::: + + +### Learner perspective + +Here are three examples of how it can look for the learner. + +:::{figure} screenshare/learner-large.png +:width: 75% + +**L1**: +Learner with a large screen, Zoom in dual-monitor mode so that the instructor +pictures are not shown. Screen-share is on the left side, collaborative notes +at bottom left, terminal and web browser on the right. +::: + +:::{figure} screenshare/learner-normal.png +:width: 75% + +**L2**: +A learner with a single large screen (Zoom in "single monitor mode"). +Instructor screen share at right, learner stuff at left. +::: + +:::{figure} screenshare/learner-small.png +:width: 75% + +**L3**: +A learner with a particularly small screen. Instructor screen-share at left, +your windows at right. +::: + + +## Share the history of your commands + +Even if you type slowly it is almost impossible to follow every command. We +all get distracted or want to read up on something or while following a command +fails on the learner laptop while instructor gets no error. + +**Add pauses** and **share the commands that you have typed** so that one can catch up. + +Below are some examples (some more successful than others) of sharing history +of commands. + +:::{figure} screenshare/history-portrait.png +:width: 50% + +**H1**: +A vertical screen layout shared. Note the extra shell history at the top. The +web browser is at the bottom, because the Zoom toolbar can cover the bottom +bit. +::: + +:::{figure} screenshare/history-rsh.png +:width: 75% + +**H2**: +This isn't a screen-share from CodeRefinery, but may be instructive. Note the +horizontal layout and shell history at the bottom right. +::: + +:::{figure} screenshare/history-landscape-dark.png +:width: 75% + +**H3**: +Similar to above, but dark. Includes contents on the right. +::: + +:::{figure} screenshare/history-portrait-light.png +:width: 50% + +**H4**: +Jupyter + terminal, including the ``fish`` shell and the terminal history. +::: + +:::{figure} screenshare/history-portrait-dark.png +:width: 50% + +**H5**: +Lesson + terminal, ``tmux`` plus terminal history and dark background. +::: + +:::{figure} screenshare/portrait.png +:width: 50% + +**H6**: +HPC Kickstart course. Note the colors contrast of the windows and colors of +the prompt and text. The history is smaller and doesn't take up primary +working space. The working directory is in the window title bar. +::: + +:::{figure} https://raw.githubusercontent.com/bast/history-window/main/demo.gif +:width: 50% + +**H7**: +Show command history "picture-in-picture", in the same terminal window. +::: + + +## How to configure history sharing + +You need to find a way to show the recent commands you have entered, so that +learners can see the recent commands. Below are many solutions. Try them out +and see what works for you. + +- [prompt-log](): + It adds a interesting idea that the command you enter is in color and also + provides terminal history before the command returns. + +- **Simple**: The simple way is `PROMPT_COMMAND="history -a"` and then + `tail -f -n0 ~/.bash_history`, but this doesn't capture ssh, + sub-shells, and only shows the command after it is completed. + +- **Better yet still simple**: Many Software Carpentry instructors use + [this script](https://github.com/rgaiacs/swc-shell-split-window), + which sets the prompt, splits the terminal window using tmux and displays command history + in the upper panel. Requirement: [tmux](https://github.com/tmux/tmux/wiki) + +- **Better (bash)**: This prints the output before the command is run, + instead of after. Tail with `tail -f ~/demos.out`. + ``` + BASH_LOG=~/demos.out + bash_log_commands () { + # https://superuser.com/questions/175799 + [ -n "$COMP_LINE" ] && return # do nothing if completing + [[ "$PROMPT_COMMAND" =~ "$BASH_COMMAND" ]] && return # don't cause a preexec for $PROMPT_COMMAND + local this_command=`HISTTIMEFORMAT= history 1 | sed -e "s/^[ ]*[0-9]*[ ]*//"`; + echo "$this_command" >> "$BASH_LOG" + } + trap 'bash_log_commands' DEBUG + ``` + +- **Better (zsh)**: This works like above, with zsh. Tail with `tail -f + ~/demos.out`. + ``` + preexec() { echo $1 >> ~/demos.out } + ``` + +- **Better (fish)**: This works like above, but for fish. Tail with + `tail -f ~/demos.out`. + ``` + function cmd_log --on-event fish_preexec ; echo "$argv" >> ~/demos.out ; end + ``` + +- **Better (tmuxp)**: This will save some typing. + [TmuxP](https://tmuxp.git-pull.com/) is a Python program (`pip install + tmuxp`) that gives you programmable `tmux` sessions. One configuration that + works (in this case for `fish` shell): + ```yaml + session_name: demo + windows: + - window_name: demo + layout: main-horizontal + options: + main-pane-height: 7 + panes: + - shell_command: + - touch /tmp/demo.history + - tail -f /tmp/demo.history + - shell_command: + - function cmd_log --on-event fish_preexec ; echo "$argv" >> /tmp/demo.history ; end + ``` + +- **Windows PowerShell**: In [Windows Terminal](https://docs.microsoft.com/en-us/windows/terminal/), + a split can be made by pressing `CTRL+SHIFT+=`. Then, in one of the splits, the following + PowerShell command will start tracking the shell history: + ``` + Get-Content (Get-PSReadlineOption).HistorySavePath -Wait + ``` + Unfortunately, this only shows commands after they have been executed. + +- [Shell exporter](https://github.com/Sabryr/Teaching-aids) can copy recent history to a remote server. + +- [history-window](https://github.com/bast/history-window): Show command + history "picture-in-picture" when teaching command line. Requires Bash. + + +## Font, colors, and prompt + +### Terminal color schemes + +- Dark text on light background, *not* dark theme. Research and our + experience says that dark-text-on-light is better in some cases and + similar in others. +- You might want to make the background light grey, to avoid + over-saturating people's eyes and provide some contrast to the pure + white web browser. (this was an accessibility recommendation when + looking for ideal color schemes) +- Do you have any yellows or reds in your prompt or program outputs? + Adjust colors if possible. + + +### Font size + +- Font should be large (a separate history terminal can have a smaller + font). +- Be prepared to resize the terminal and font as needed. Find out + the keyboard shortcuts to do this since you will need it. + + +### Prompt + +At the beginning of the workshop your goal is to have a shell +**as easy to follow as possible** and **as close to what learners will +see on their screens**: +- Your prompt should be minimal: few distractions, and not take up many + columns of text. +- [prompt-log]() does + this for you. +- The minimum to do is is `export PS1='\$ '`. +- Blank line between entries: `export PS1='\n\$ '`. +- Have a space after the `$` or `%` or whatever prompt character you + use. +- Strongly consider the Bash shell. This is what most new people will + use, and Bash will be less confusing to them. +- Eliminate menu bars and any other decoration that uses valuable + screen space. +- Add colors only if it simplifies the reading of the prompt. + +Later in the workshop or in more advanced lessons: +- Using other shells and being more adventurous is OK - learners will + know what is essential to the terminal and what is extra for your + environment. + +Try to find a good balance between: +- Showing a simple setup and showing a more realistic setup. +- Showing a consistent setup among all instructors and showing a + variety of setups. + + +## Habits we need to un-learn + +- **Do not clear the terminal**. Un-learn CTRL-L or `clear` if possible. + More people will wonder what + just got lost than are helped by seeing a blank screen. Push + ``ENTER`` a few times instead to add some white space. +- **Do not rapidly switch between windows** or navigate quickly between multiple + terminals, browser tabs, etc. This is useful during your own work when nobody + is watching, but it is very hard to follow for learners. +- Avoid using **aliases** or **shortcuts** that are not part of the + standard setup. Learners probably don't have them, and they will fail + if they try to follow your typing. Consider even to rename corresponding + files (`.bashrc`, `.gitconfig`, `.ssh/config`, `.ssh/authorized_keys`, `.conda/*`). +- Be careful about using **tab completion** or **reverse history search** if these + haven't been introduced yet. + + +## Desktop environment and browser + +- Try to remove window title bars if they take up lots of space + without adding value to the learner. +- Can you easily resize your windows for adjusting during teaching? +- Does your web browser have a way to reduce its menu bars and other + decoration size? + - Firefox-based browsers: go to `about:config` and set + `layout.css.devPixelsPerPx` to a value slightly smaller than one, + like `0.75`. Be careful you don't set it too small or large since + it might be hard to recover! When you set it to something smaller + than 1, all window decorations become smaller, and you compensate + by zooming in on the website more (you can set the default zoom to + be greater than 100% to compensate). Overall, you get more + information and less distraction. + + +## How to switch between teaching setup and work setup? + +- Make a dedicated "demos" profile in your terminal emulator, if + relevant. Or use a different terminal emulator just for demos. +- Same idea for the browser: Consider using a different browser profile for + teaching/demos. +- Another idea is to containerize the setup for teaching. + We might demonstrate this during the {ref}`cool-gems` session later. + +--- :::{keypoints} -- Here we summarize keypoints. +- Share **portrait layout** instead of sharing entire screen +- **Adjust your prompt** to make commands easy to read +- **Readability** and beauty is important: adjust your setup for your audience +- **Share the history** of your commands +- Get set up a **few days in advance** and get feedback from someone else. + Feedback and time to improve is very important to make things clear and accessible. + 10 minutes before the session starts is typically too late. ::: + + +## Exercises + +:::{exercise} Evaluate screen captures (20 min) + +Evaluate screenshots on this page. Discuss the trade-offs of each one. Which +one do you prefer? Which are useful in each situation? + +Please take notes in the collaborative document. +::: + +:::{exercise} Set up your own environment (20 min) + +Set up your screen to teach something. Get some feedback from another learner +or your exercise group. +::: + + +## Other resources + +- +- diff --git a/content/screenshare/history-landscape-dark.png b/content/screenshare/history-landscape-dark.png new file mode 100644 index 0000000..a1aef3c Binary files /dev/null and b/content/screenshare/history-landscape-dark.png differ diff --git a/content/screenshare/history-portrait-dark.png b/content/screenshare/history-portrait-dark.png new file mode 100644 index 0000000..2fc1fa6 Binary files /dev/null and b/content/screenshare/history-portrait-dark.png differ diff --git a/content/screenshare/history-portrait-light.png b/content/screenshare/history-portrait-light.png new file mode 100644 index 0000000..5f4361c Binary files /dev/null and b/content/screenshare/history-portrait-light.png differ diff --git a/content/screenshare/history-portrait.png b/content/screenshare/history-portrait.png new file mode 100644 index 0000000..28e18b0 Binary files /dev/null and b/content/screenshare/history-portrait.png differ diff --git a/content/screenshare/history-rsh.png b/content/screenshare/history-rsh.png new file mode 100644 index 0000000..1bbb1cc Binary files /dev/null and b/content/screenshare/history-rsh.png differ diff --git a/content/screenshare/instructor.png b/content/screenshare/instructor.png new file mode 100644 index 0000000..718f2a8 Binary files /dev/null and b/content/screenshare/instructor.png differ diff --git a/content/screenshare/landscape.png b/content/screenshare/landscape.png new file mode 100644 index 0000000..eda9d42 Binary files /dev/null and b/content/screenshare/landscape.png differ diff --git a/content/screenshare/learner-large.png b/content/screenshare/learner-large.png new file mode 100644 index 0000000..3b6d2cd Binary files /dev/null and b/content/screenshare/learner-large.png differ diff --git a/content/screenshare/learner-normal.png b/content/screenshare/learner-normal.png new file mode 100644 index 0000000..590135e Binary files /dev/null and b/content/screenshare/learner-normal.png differ diff --git a/content/screenshare/learner-small.png b/content/screenshare/learner-small.png new file mode 100644 index 0000000..5d5f421 Binary files /dev/null and b/content/screenshare/learner-small.png differ diff --git a/content/screenshare/portrait.png b/content/screenshare/portrait.png new file mode 100644 index 0000000..415799f Binary files /dev/null and b/content/screenshare/portrait.png differ