Creating interactive tutorials with Jupyter Notebooks

We are always looking for ways to engage and help our users understand and use Contentful in faster and better ways. That's why I started looking into tools for providing interactive, step-by-step tutorials, in which our users could start following a simple and engaging guide in their chosen language. This guide would show users the basics of working with Contentful and how to achieve a few different tasks; like displaying content, rendering an HTML page, or artsy graphs.

One tool definitely came to my mind for achieving creating interactive tutorials — Jupyter Notebooks, an interactive coding platform mainly for Python but with support for other language engines, which supports data visualizations and in-browser code editing and execution.

A main challenge is hosting the Jupyter notebook so users are able to modify and run existing code. Fortunately, a project called BinderHub, a Docker-based JupyterHub executing environment (a Jupyter notebook multi-user interface), solves that. BinderHub allows us to configure our repository with a Dockerfile, which specifies all the dependencies for every language we require, while also enabling deployment using MyBinder, a BinderHub cloud solution for users to consume the tutorial.

Setting up a story for the Jupyter notebook tutorial

For our case, we want to be able to write and run snippets for a tutorial, have some Markdown to explain each step, and then display rendered HTML and graphs. All this was doable by Jupyter, and I only had to do some additional coding to use the templating engine we wanted for each of our languages–this extra bit of code is included in the tutorials.

With this objective in mind, I set up an example space in Contentful to facilitate my storytelling for the tutorial.

The story begins with an artist named John Doe, who has some math-based art, and we as art enthusiasts want to take a look at his art. Within the example space in Contentful, I then create two content types: Person and Scatter Data that would be used in the building of a solution to his problems:

• With the Person content type, we can define the biography of an artist, which we would use for displaying content from simple text to a generated HTML view of their bio.

• With the Scatter Data content type, for which each entry is a point in an X/Y cartesian axis, we can define the works of art for John. Normally, another content type like Artwork, should be defined and used to group Scatter Data entries.

Start building

Sign up for a free Contentful account

Use your favorite tech stack, language, and framework of your choice.

Telling a compelling story

I've already given you a glimpse into the story of our mad math artist John Doe, a creator of graph art who has been sloppy in how he’s saved and catalogued everything.

But the interesting part is the process of coming up with a compelling story to guide you through a tutorial. So, here’s a list of steps necessary to devising your own interactive tutorial:

1. List your objectives (e.g., fetch data from Contentful, render plain text, render HTML, show some graphs)

2. Describe the resources required for each your objectives (e.g., a Contentful space, simple textual data, an image, labeled Cartesian coordinates)

3. Find a theme that can link everything together (e.g. John is a math artist who creates artwork out of scatter plots)

4. Define the steps of your story exploration (e.g. find out who John is, how he gets his artworks mixed up, sort through the mess to find actual art)

5. Write out the story

Creating a story-based tutorial

With the story at hand, we can embark into the tutorial writing. These are the clearly-defined steps for our example:

1. Create a Contentful client

2. Fetch John Doe's biography

3. Display it as simple text

4. Setup HTML + Markdown rendering

5. Render biography in HTML

6. Display his art

7. Unscramble his art

8. Properly label his art

9. Identifying next steps for the user

With this outline, we move on to write our tutorial using Markdown while interlining code snippets in between—Jupyter has native support for Markdown snippets.

Incorporating other languages in the Jupyter tutorial

By default, Jupyter allows you to write interactive Python notebooks, but is also extensible to other languages via different kernels. Fortunately, there are maintained kernels for many languages minus Swift that we support in Contentful. Using the kernels, I constructed our tutorial for Ruby, and I'm looking forward to do the same for our other supported languages.

What lies ahead

I'm looking forward to adding all Contentful’s supported languages to the project before expanding and refining it so that first-time Contentful users can get the best learning tools available.

You can see the progress of the project on my personal GitHub.

Now that you’ve learned, creating a Contentful account is free and easy. And once you’ve built something with Contentful, be sure to share it with us to get featured.

Subscribe for updates

Build better digital experiences with Contentful updates direct to your inbox.