Hi folks,
I don't know about you, but I learn best in an interactive setting, where I'm engaged with the material I'm trying to learn, where there is a tight feedback loop that allows me to see right away whether my understanding is correct or not. I know I'm not alone in this, as decades of Lisp culture around REPL-driven development attests.
So why is it that the default way to learn a new library in Racket is to read the docs? Most docs aren't set up to help you learn in an interactive way, and, indeed, documentation is written to serve many different goals, only one of which is to help you learn. The others include: to serve as a reference, to serve as a troubleshooting resource, to provide a view into the implementation, the mechanisms, and design choices, and more. Good documentation must achieve all of these goals, and teaching poor you how to use the dang thing isn't always the top priority.
Well, no more! With the specific goal of learning in mind, Qi now offers an interactive tutorial optimized for the Racket ecosystem. This was made possible by the help of Stephen De Gabrielle @spdegabrielle , who first suggested distributing a runnable Qi application, and Laurent Orseau @Laurent.O who added really nifty support for this format for DrRacket users. This post is not about Qi, but rather about the format of this tutorial, which may be of interest as it could be broadly adopted.
What is the tutorial format?
The tutorial is just a Racket source tree - a collection of Racket modules. It is structured as a series of comments containing the tutorial material, interspersed with code illustrating the ideas described (i.e. similar to many of the language-oriented tutorials on "Learn X in Y minutes" (https://learnxinyminutes.com/)).
As Matthew Butterick says, "the book is a program." And with this style of tutorial, to turn it around, "the program is a book."
Since these are just normal Racket modules, they allow and encourage you to try out variations inline and experiment on your own before proceeding -- add marginalia, if you will. And just like in any textbook, there are also included exercises to practice your skills and develop fluency.
How is it distributed?
It is distributed using the handy from-template package by Philip Dumaresq.
To get started on a tutorial, you simply need to install from-template:
raco pkg install from-template
And then run this at the command line to install a tutorial:
raco new <tutorial-name>
And you now have a working Racket source tree containing a runnable tutorial for the new library (e.g. for Qi's tutorial, use raco new qi-tutorial). Btw, note that from-template is intended to distribute templates for Racket projects in general (like Python's Cookiecutter), and is not specific to tutorials.
Another way to distribute the tutorial could be something like Denxi, but I haven't had a chance to explore this option yet.
Where could this style of tutorial be used?
For any library that has a nontrivial learning component. I can think of a few libraries off the top of my head that could benefit from a tutorial in this format:
- megaparsack (whose tutorial is already excellent, and could easily be provided in interactive format virtually as is)
- rosette (I think a lot of people (myself included) are curious about Rosette, and an interactive tutorial would certainly lower the barrier to entry and open the door to learning what it can do)
- brag
... not to mention many specialized areas of Racket more generally, such as syntax-parse.
How can I adopt this for my library?
- Write the tutorial and put it in a dedicated repo e.g.
mylibrary-tutorial(you could just start with a placeholder first and improve the tutorial over time until it's ready to be announced) - Host it on e.g. GitHub or GitLab
- Register your tutorial for distribution by submitting a PR to add it on the racket-templates repo
- Link to it in your docs (example)
- Announce it
Why should libraries consider providing an interactive tutorial? Aren't the docs enough?
With documentation, I think it's fine to say the same thing many times in many different ways (e.g. this great talk by Jacob Kaplan-Moss, one of the authors of the widely admired Django docs (and Django 
)).
In that spirit, for library authors, a tutorial isn't an alternative but a complement to other docs. It tells your users that you care about their time and want to make sure they don't waste it reading things they won't understand until they are ready.
For users, just consider this: in order to learn a new library, would you rather (A) read or (B) play?
I rest my case 
Finally,
Are you sure this format is the right one?
No. Ideas welcome!
-Sid
