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 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.
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:
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:
With the story at hand, we can embark into the tutorial writing. These are the clearly-defined steps for our example:
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.
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.
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.