Installation and Setup
How to Make an Oriole with LaunchBot
Tips for Creating a Notebook
Tips for Recording an Oriole
Oriole is a unique new medium that blends code, data, text, and video into a narrated learning experience with executable content. You can see a few examples here, or take a look at the complete collection on Safari.
LaunchBot helps you discover, build, and run Docker-enabled content, such as Jupyter Notebooks and Orioles. It provides a desktop GUI in place of many of the complex command-line process for installing and running applications. Think of LaunchBot as the place authors and editors will work together to create compelling text and runnable code, and as a tool that will help production ensure that all of the dependencies are captured in the Dockerfile so that the Oriole or notebook will run as expected.
You can learn more about LaunchBot here.
To check whether you have Git installed already, type git at the command line in a terminal window. If you see output that describes common Git commands, you have Git installed.
Use git config to specify your email address (you’ll need to use the same email address you use to log in to GitLab, which we’ll discuss below). Here are instructions. It’s important that you use the same email address here as you do in GitLab, so you’ll be able to push changes to the remote GitLab repository.
If you already have Docker installed, please make sure it’s updated to the latest version.
Docker is needed to build an Oriole, and “Docker for Mac” is an easy way to get Docker up and running on your Mac. Follow the instructions here to download and install Docker for Mac.
GitLab makes it easy to get a Git repo and add collaborators to work together on an Oriole project. We’ll get you started with a template that includes a base Dockerfile that’s appropriate for your project, and we’ll invite you to create a GitLab account. You’ll use HTTPS to clone your project into LaunchBot.
launchbot at the command line or double clicking the icon. LaunchBot will start in your default browser (should be Chrome or Firefox).Now that all of the pieces are in place, we’ll take you through the steps to start a new Oriole project.
download. The project will now appear under Your Projects and a project directory will be made in ~/launchbot/<project name>.authoring_branch).After you are satisfied with the changes you have made:
15-25 minutes The Oriole should not be longer than 25 minutes; explicit details can be put in the text. Essentially, an Oriole is the author explaining the progress of code through the notebook.
Write an article The Oriole notebook should read like an article and “stand alone” with subtitles and headers. The text refers to what the code does; feel free to write specifics in the text that you may not have time for in the video.
Cell output I It is more interesting for the user when running the cell to see output. Find a balance between short code blocks and making sure there is output for code blocks. If the code is too long, break it into multiple blocks.
Cell output II Keep output to a reasonable length. For rows, 3-5 should suffice. For columns, display just the ones you are talking about, if not all are relevant.
Data/files must be local Don’t pull anything from the internet. If code for downloading is important for your Oriole, please use an if-statement, e.g., if not exist: code to download.
Small datasets Keep datasets small and quickly executable. Create a subset and refer to the larger dataset for viewers to use on their own. Long datasets cause long execution times and confuse viewers.
Exercises Having exercises, or suggesting specific parameters to change in the code, is an excellent use of the Oriole format. Try to be explicit about what output/solution is expected.
Links When adding links to the text, make sure to use HTML notation rather than markdown. For example, instead of [go to this link](http:///www.oreilly.com) use <a href="http://www.oreilly.com" target="_blank">go to this link</a> The target="_blank" is very important, to ensure that the link opens in a new window rather than the Oriole window.
Math When formatting equations, please use a markdown editor, such as http://dillinger.io/, to check it is formatted correctly. For example, $\Theta(n^2)$ will render correctly in the jupyter notebook, but to render correctly in the final version, it should be $$\Theta(n^2)$$.
Importing libraries Import libraries into the cell where they’re first needed to make it easier for the viewer to follow.
Re-running cells Consider that the user may go back to re-run individual cells.
Final check Before submitting, please do a final run through of the notebook by 1. creating a new image from the dockerfile ( --no-cache parameter when building), 2. disconnecting from the internet, 3. starting a new container 4. running all notebooks and every cell.
Be explicit I Be sure to explicitly mention, out loud, when the user should click Run during recording. The user does not see you scrolling and clicking through the notebook - they can only respond to your audio cues.
Be explicit II When recording, refer specifically to “Run” cells when you are talking about them, in a way that makes them easily identifiable for cueing and for viewers. The number of the cell is not a way to identify the cell, as a) the number in a regular jupyter notebook is not based on cell placement, but rather usage and b) the numbers do not appear in the Oriole.
Repeatable results If you refer to a specific result, make sure what you say will happen each and every time the code is executed.
Exercises If you have exercises, tell the viewers to pause the video while they work on the exercise. Take a second or two and then continue talking (perhaps starting with a “welcome back”); this makes the final cut of the video smoother.
Conclusion Feel free to conclude your recording by thanking the audience. You do not need to add a written conclusion within the notebook.