Package Overview

Overview

The Package Overview format is a tutorial where you want to help learners become familiar with a particular package or library that they may find useful. The goal is to help them understand the core logic of the package, have some sense of what it can be used for, and get familiar with how to navigate the documentation and learn more on their own later.

You cannot cover the entire package in 1 hour. People will not be competent users of the package after one hour. The goal is to get them familiar with it to get over the initial issues that confuse people and prevent them from using the package.

If the package is large, you may need multiple tutorials, even for an overview.

For example:

• R ggplot2 for data visualization

• R rvest for web scraping

• Python textblob for working with text

• Biopython

What are your 3-6 sections?

What should someone know to start using this package? Identify 3-6 things. These "things" could be:

• A function

• A set or class of functions

• A class or object specific to the package

• A core workflow of a few lines of code: for packages where you typically need to run 2-4 lines of code to get things set up (make a plot, scrape a website and access the content, import and process text files into a corpus). A very minimal version that will still do something.

• A variation on a function or workflow, such as a different input or a related function

If you come up with more than 3-6 things, then you need more than one tutorial -- split it up into multiple parts.

Writing the Exercise Outline

The Package Overview tutorial type gives you the most flexibility to experiment with different types of exercises. But when you're writing your outline, focus first on what concepts you want people to practice, NOT the type of exercise. You can figure out the exercise type later. Start with a list of the functions, use cases, options, etc. (see the list in the 3-6 sections part above) that you want learners to practice. This is your exercise outline.

Your exercise outline will define your 3-6 sections. You will write the teaching materials you need to teach learners the skills to complete each exercise. This exercise-first approach is useful for helping you focus your tutorial. Package Overview tutorials can quickly get bloated and try to cover too much. By focusing first on the 3-6 things you want learners to practice via exercises, and then teaching to those exercises, you'll naturally narrow the scope of what you're covering and help yourself avoid going off on tangents.

If it's not important enough to be an exercise (or at least be supporting material for an exercise), then it's probably not important enough to cover in the tutorial.

Example

A quick introduction to ggplot2 - for data visualization in R.

Exercise Outline

• Basic ggplot template code (ggplot(aes()) + geom()

• Use a different geom function

• Set the color aesthetic to color points by group

• Add title and axis labels to the plot with labs()

• Add facets to a plot

• Use a built in theme and change bar/plot color (not from aes mapping)

Note: this is a lot to cover in an hour. It took some practice and refinement of the tutorial over time to get it streamlined down to an hour and still cover all of these topics.