With 1.0 approaching it’s a good time to improve learning materials, especially for getting to know the language.
A while a ago I posted this idea on Github A Tour of Crystal · Issue #4462 · crystal-lang/crystal · GitHub and it was well received, yet nothing came out of it so far. Let’s get this started!
An important feature is to allow interactive execution of code. Examples should be alive instead of just for reading. And you shouldn’t have to install Crystal to try it.
Still, a good tutorial doesn’t just consist of a series of examples. They need to be accompanied by good explanations (or rather, the examples should accompany the explanations). An ideal format for that are lessons which cover a topic with several aspects and show examples as embedded code playgrounds. Smaller lessons might have only one example, bigger ones can have more than one.
The reader gets the ability to directly run the code and fiddle with it, to improve understanding on what it does.
I built an embeddable playground that runs code on https://carc.in and can easily be integrated with a tutorial. You can take a look at an example here: Hello World - Crystal
It works very well with mkdocs-material, so we can easily use it in crystal-lang/crystal-book.
Still need to consider if we might want it as a separate project, but I think there are good reasons to just let the tutorial be part of crystal-book.
For this we should revisit the navigation layout (see Reorganize content structure · Issue #384 · crystal-lang/crystal-book · GitHub). I think nav tabs would be a good idea to clearly separate different sections of the site (language reference vs. tutorial vs. other resources).
And now it’s time for creating some content. I’ve already started on a couple of introductory lessons. Maybe some might join me? We should start a separate discussion on the curriculum.
For now, I’m mostly interested in discussing the general idea (and maybe the playground embed specifically).
