add a ton of documentation on Big Blue Button

howto/conference.md

@@ -16,12 +16,280 @@ considered out of scope here.
 
 # Tutorial
 
-<!-- simple, brainless step-by-step instructions requiring little or -->
-<!-- no technical background -->
+## Connecting to Big Blue Button with a web browser
+
+The Tor Big Blue Button (BBB) server is currently hosted at
+<https://tor.meet.coop/>. Normally, someone will start a conference
+and send you a special link for you to join. You should be able to
+open that link in any web browser (including mobile phones) and join
+the conference.
+
+The web interface will ask you if you want to "join the audio" through
+"Microphone" or "Listen only". You will typically want "Microphone"
+unless you really never expect to talk via voice (would still be
+possible), for example if your microphone is broken or if this is a
+talk which you are just attending.
+
+Then you will arrive at an "echo test": normally, you should hear
+yourself talk. The echo test takes a while to load, you will see
+"Connecting to the echo test..." for a few seconds. When the echo test
+start, you will see a dialog that says:
+
+> This is a private echo test. Speak a few words. Did you hear audio?
+
+Typically, you will hear yourself speak with a slight delay, if so,
+click "Yes", and then you will enter the conference. If not, click
+"No" and check your audio settings. You might need to reload the web
+page to make audio work again.
+
+When you join the conference, you may be muted: click on the "crossed"
+microphone at the bottom of the screen to unmute yourself. If you have
+a poor audio setup and/or if your room is noisy, you should probably
+mute yourself when not talking.
+
+See below for tips on improving your audio setup.
+
+## Sharing your camera
+
+Once you are connected with a web browser, you can share your camera
+by clicking the crossed camera icon in the bottom row. See below for
+tips on improving your video setup.
+
+## Sharing your screen or presentation
+
+To share your screen, you must be a "presenter". A moderator
+(indicated by a square in the user list on the left), can grant you
+presenter rights. Once you have those privileges, you can enable
+screen sharing with the right-most icon in the bottom row, which looks
+like a black monitor.
+
+Note that Firefox in Linux cannot share a specific monitor: only your
+entire display, see [bug 1412333](https://bugzilla.mozilla.org/show_bug.cgi?id=1412333). Chromium on Linux does not have
+that problem.
+
+Also note that if you are sharing a presentation, it might be more
+efficient to *upload* the presentation. Click on the "plus" ("+"),
+leftmost icon in the bottom row. PDFs will give best results, but that
+feature actually supports converting any "office" (Word, Excel, etc)
+document.
+
+Such presentations are actually whiteboards that you can draw on. A
+moderator can also enable participants to collaboratively draw over it
+as well, using the toolbar on the right.
+
+The "plus" icon can also enable sharing external videos or conduct polls.
+
+## Connecting with a phone
+
+When you join a conference with a web browser, at the top of the chat
+window, you should see a message that looks something like this:
+
+> Dial in number is 123.456.7890.
+> SIP dial in URI is 987654321@sip.ca.meet.coop.
+> Confrence PIN is 0000000.
+
+The "Dial in number" actually allows other participants to call in a
+phone number (redacted as "123-456-7890" above) and then enter a
+conference PIN (redacted as "0000000" above) to enter the call with
+any plain old telephone or cellular phone. Users may need to unmute by
+hitting the "zero" ("0" on the keypad) on their phone.
 
 # How-to
 
-<!-- more in-depth procedure that may require interpretation -->
+## Hosting a conference
+
+To host a conference in BBB, you need an account. Ask a BBB admin to
+grant you one (see the [service list](service) to find one) if you do not
+already have one. Then head to <https://tor.meet.coop/> and log
+in. 
+
+You should end up in your "Home room". It is fine to host ad-hoc
+meetings there, but for regular meetings (say like your team
+meetings), you may want to create a dedicated room.
+
+Each room has its own settings where you can, for example, set a
+special access code, allow recordings, mute users on join, etc. You
+can also share a room with other users to empower them to have the
+same privileges as you.
+
+Once you have created the conference, you can copy-paste the link to
+others to invite them.
+
+## Breakout rooms
+
+As a moderator, you also have the capacity of creating "breakout
+rooms" which will send users in different rooms for a pre-determined
+delay. This is useful for brainstorming sessions, but can be confusing
+for users, so make sure to explain clearly what will happen
+beforehand, and remind people before the timer expires. 
+
+A common issue that occurs when breakout room finish is that users may
+not automatically "rejoin" the audio, so they may need to click the
+"phone" button again to rejoin the main conference.
+
+## Improving your audio and video experience
+
+Remote work can be hard: you simply don't have the same "presence" as
+when you are physically in the same place. But we can help you get
+there. 
+
+[Ben S. Kuhn][] wrote this extraordinary article called "[How to make
+video calls almost as good as face-to-face][]" and while a lot of its
+advice is about video (which we do not use as much), the advice he
+gives about audio is crucial, and should be followed.
+
+[How to make video calls almost as good as face-to-face]: https://www.benkuhn.net/vc/
+[Ben S. Kuhn]: https://www.benkuhn.net/
+
+This section is strongly inspired by that excellent article, which we
+recommend you read in its entirety anyways.
+
+### Audio tips
+
+Those tips are critical in having a good audio conversation
+online. They apply whether or not you are using video of course, but
+should be applied *first*, before you start going into a fancy setup.
+
+All of this should cost less than 200$, and maybe as little as 50$.
+
+Do:
+
+ 1. ensure a **quiet work environment**: find a quiet room, close the
+    door, and/or schedule quiet times in your shared office for your
+    meetings, if you can't have your own office
+
+ 2. if you have network issues, **connect to the network with cable**
+    cable instead of WiFi, because the problem is [more likely to be
+    flaky wifi][] than your uplink
+
+[more likely to be flaky wifi]: https://www.benkuhn.net/wireless/
+
+ 3. buy **comfortable** headphones that **let you hear your own
+    voice**, that is: normal headphones without noise reduction, also
+    known as [open-back headphones][]
+
+[open-back headphones]: https://www.soundguys.com/open-back-vs-closed-back-headphones-12179/
+
+ 4. use a headset mic -- e.g. [BoomPro][] (35$), [ModMic][] (50$) --
+    which will sound better and pick up less noise (because closer to
+    your mouth)
+
+[ModMic]: https://antlionaudio.com/products/modmic-uni
+[BoomPro]: https://www.sweetwater.com/store/detail/BoomProMic--v-moda-boompro-microphone-communication-mic-for-headphones
+
+You can combine items 3 and 4 and get a USB headset with a boom
+mic. Something as simple as the [Jabra EVOLVE 20 SE MS][] (65$)
+should be good enough until you need professional audio.
+
+[Jabra EVOLVE 20 SE MS]: https://www.jabra.com/business/office-headsets/jabra-evolve/jabra-evolve-20
+
+Do not:
+
+ 1. **avoid wireless** headsets because it introduces a *lot* of
+    latency
+ 
+ 2. **avoid wifi** because it will introduce reliability and latency
+    issues
+
+Then, as Ben suggests:
+
+> You can now leave yourself unmuted! If the other person also has
+> headphones, you can also talk at the same time. Both of these will
+> make your conversations flow better.
+
+This idea apparently comes from [Matt Mullenweg][] -- Wordpress
+founder -- who prominently featured the idea on his blog: "[Don't
+mute, get a better headset][]".
+
+[Don't mute, get a better headset]: https://ma.tt/2020/03/dont-mute-get-a-better-headset/
+[Matt Mullenweg]: https://ma.tt/
+
+### Video tips
+
+Here are, directly from from [Ben's article][], notes specifically
+about video conferencing. I split it up in a different section because
+we mostly do *audio-only* meeting and rarely open our cameras.
+
+[Ben's article]: https://www.benkuhn.net/vc/
+
+So consider this advice purely optional, and mostly relevant if you
+actually stream video of yourself online regularly.
+
+> 6. (~$200) Get a second monitor for notes so that you can keep Zoom
+>    full-screen on your main monitor. It’s easier to stay present if
+>    you can always glance at people’s faces. (I use an iPad with
+>    Sidecar for this; for a dedicated device, the right search term is
+>    “portable monitor”. Also, if your meetings frequently involve
+>    presentations or screensharing, consider getting a third monitor
+>    too.)
+>
+> 7. ($0?) Arrange your lighting to cast lots of diffuse light on your
+>    face, and move away any lights that shine directly into your
+>    camera. Lighting makes a bigger difference to image quality than
+>    what hardware you use!
+>
+> 8. (~$20-80 if you have a nice camera) Use your camera as a
+>    webcam. There’s software for [Canon][], [Fujifilm][],
+>    [Nikon][], and [Sony][] cameras. (You will want to be able to
+>    plug your camera into a power source, which means you’ll probably
+>    need a “dummy battery;” that’s what the cost is.)
+>
+> 9. (~$40 if you have a smartphone with a good camera) Use that as a
+>    webcam via [Camo][].
+>
+> 10. (~$350) If you don’t own a nice camera but want one, you can get
+>     a used entry-level mirrorless camera + lens + dummy battery +
+>     boom arm. See [buying tips][].
+
+[buying tips]: https://www.benkuhn.net/vc/#a-note-on-camera-buying
+[Camo]: https://reincubate.com/camo/
+[Sony]: https://support.d-imaging.sony.co.jp/app/webcam/en/
+[Nikon]: https://downloadcenter.nikonimglib.com/en/download/sw/176.html
+[Fujifilm]: https://fujifilm-x.com/en-us/support/download/software/x-webcam/
+[Canon]: https://www.usa.canon.com/internet/portal/us/home/support/self-help-center/eos-webcam-utility
+
+This section is more involved as well, so I figured it would be better
+to prioritise the *audio* part (above), because it is more important
+anyways.
+
+Of the above tips, I found most useful to have a second monitor: it
+helps me be distracted *less* during meetings, or at least it's easier
+to notice when something is happening in the conference.
+
+## Testing your audio
+
+Big Blue Button actually enforces an echo test on connection, which
+can be annoying (because it's slow, mainly), but it's important to
+give it a shot, just to see if your mic works. It will also give you
+an idea of the latency between you and the audio server, which, in
+turn, will give you a good idea of the quality of the call and its
+interactions.
+
+But it's not as good as a real mic check. For that, you need to record
+your voice and listen to it later, which an echo test is not great
+for. There's a site called [miccheck.me][], [built with free
+software][], which provides a client-side (in-browser) application to
+do an echo test. But you can also use any recorder for this purpose,
+for example [Audacity][] or any basic sound recorder.
+
+[Audacity]: https://www.audacityteam.org/
+[built with free software]: https://github.com/onetwothreebutter/mic-check
+[miccheck.me]: https://www.miccheck.me/
+
+You should test a few sentences with specific words that "pop" or
+"hiss". Ben (see above) suggests using one of the [Harvard
+sentences][] (see also [wikipedia][]).
+
+[wikipedia]: https://en.wikipedia.org/wiki/Harvard_sentences
+[Harvard sentences]: https://www.cs.columbia.edu/~hgs/audio/harvard.html
+
+To quote Ben again:
+
+> If those consonants sound bad, you might need a better windscreen,
+> or to change how your mic is positioned. For instance, if you have a
+> headset mic, you should position it just beside the corner of your
+> mouth—not directly in front—so that you’re not breathing/spitting
+> into it.
 
 ## Pager playbook