How to prepare a quality screen-share

Objectives

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

Discussion: 15 min
Exercises: 15 min

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, which sets the prompt, splits the terminal window using tmux and displays command history in the upper panel. Requirement: tmux

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 is a Python program (pip install tmuxp) that gives you programmable tmux sessions. One configuration that works (in this case for fish shell):

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, 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.
Tavatar: shell history mirroring teaching tool can copy recent history to a remote server.
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 Sharing teaching gems session later.

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

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.

Set up your own environment (20 min)

Set up your screen to teach something. Get some feedback from another learner or your exercise group.

How to prepare a quality screen-share

Share portrait layout instead of sharing entire screen when teaching online

Instructor perspective

Learner perspective

Share the history of your commands