Suggestions for reproducible tutorials

From jbay808 on HackerNews:

When I was first starting, I almost gave up on Python because the print “Hello world” script that I copy-pasted from an online tutorial failed to run.

The hardest part (for me) of getting started with a new language is setting up the environment to run properly… Installing libraries, configuring environment variables, pointing the IDE to the interpreter, etc. So of course that’s where I assumed my mistake was.

It was only much later that I realized that I was running Python 3 (newer is better right?) and the tutorial was written when Python 2 was the latest version. So the print statements changed.

And of course, “print” is in everyone’s first program. So it broke the experience for all first time users.

Julia’s story on installation and reproducibility is much better than it was, and better than Python’s. On the other hand, tutorials/demos tend to be the exception, because of the assumption that the user is working in a clean base environment (which won’t be true for long if a new user tries out a series of tutorials). Some of my memorable first experiences with Julia were errors produced by not having the correct version of a package installed to go along with the tutorial. A secondary issue is that I had added packages to my base environment, resulting in cluttered/conflicting manifest.

I recognize that the point of tutorials is to show what one can do with some particular set of packages, and that introduction to Julia workflows, best practices, etc is out of scope. However, if new users don’t get past these initial hurdles, the tutorial can’t effectively on-board new users.

My suggestion would be to provide for a tutorial:

  • A project file that is sufficient to reproduce the tutorial
  • Some pointers to how to set up the project environment prior to running the tutorial

I think this would go a long way toward improving the typical experience of Julia newcomers.

4 Likes

For Pluto.jl this is done by embedding the Project and Manifest files into the notebook file, se 🎁 Built-in Pkg management by fonsp · Pull Request #844 · fonsp/Pluto.jl · GitHub

3 Likes

Yup, that’s a good point. I typically try to include the project and manifest files in the same folder as the tutorial, and I also like to explicitly add the Pkg.activate step to the tutorial itself so that a user following along will automatically get the right environment, as in EdgeCameras.jl/demo.ipynb at master · rdeits/EdgeCameras.jl · GitHub

I wasn’t aware that Pluto can embed the project files into the document–that’s super cool.

1 Like

It is in the current main branch and will be in the upcoming 0.15 release.