Interactive Tutorial

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).

19 Likes

I’m all in for this, I think we definitely need to have something like this for 1.0.0. As an example Go 1.0 release had this as Go Tour and I know a lot of people (even around me) picked the language really quickly because of that.
Let’s have a talk about how can we achieve this.

2 Likes

Oh, the ergonomics are well done!
It’s great for easing the learning curve :+1:

Here is a preivew of the first couple of lessons: Basics - Crystal

1 Like

And this is a first proposal of a curriculum:

  • Basics
    • Hello World
    • Variables
    • Basic Math
    • Strings
    • Control Flow
    • Methods
    • Testing
  • Collections (maybe this shouldn’t be a course but one or several lessons in the advanced course?)
    • Array
    • Hash
    • Enumerable
    • Iterator
    • Map/Reduce
    • Tuples and NamedTuples
    • Slice and StaticArray
  • Advanced
    • String composition
    • Regular Expressions
    • Time and Date
    • Advanced Math - Non-default Types, Overflow, Big numbers
    • Char
    • Blocks and Procs
    • Streaming IO
    • Exceptions
    • Concurrency and Parallelism
    • Ecosystem / Shards
  • Types (parts of the specification can be re-used for this)
    • Instance Variables and Accessors
    • Instance methods
    • Inspection
    • Equality and Comparability
    • Classes, structs and modules
    • Class Variables and Methods
    • Serialization
    • Inheritance
    • Redefining and overriding
    • Generics
  • Metaprogramming (parts of the specification can be re-used for this)
    • Macro basics
    • Reflection
    • Macro methods
    • Macro hooks

It’s just a draft and obviously not complete. It will probably take some time to implement all lessons, but it’s still good to plan ahead. For the first iteration I’d like to focus on a single course, and what’s better than the introduction? =)
WDYT?

9 Likes

I think this is great, and would like to contribute to it.

In addition to a presentation of the semantics and structure of the language, I think most users (especially newbies and converts from Ruby, and other dynamic languages in particular) would get the most out of examples of actual use cases.

So I would have also structure the docs to explain/show some standard use case categories.

For example:

Inputing/Outputting
The most common thing just about every programmer has to do is get data into and out of programs, in the necessary formats. I think a whole section of examples on how to do this, for various types of things (numbers, strings, files, etc) is essential to help people get their programs working with real data.

I can’t tell you the hours of frustrations I’ve spent with many languages trying to figure out how to just read numbers from the command line into my programs,and how to format them for different styles of output. The same can be said of strings, files, etc.

Times/Dates
This is another thing that is commonly done that should have explicit examples for various use cases.

Common things like how to measure time differences (stopwatch times), and the use of things like Time.monotonic and how to get outputs in different times units (secs, msec, usecs, etc), and how to round time to significant digits. Also of course, how to determine times in different locations, and use/output in different time/date formats. These kind of things are particularly important for people doing web apps.

Arithmetic
Coming primarily from Ruby, probably the biggest recurring PITA is grokking how to do math, in a strict typing language, to get the programs to compile, and prevent overflows.

This would explain the precedence of operators, and the order of doing math with different sized types, and when/how to use the overflow operators, &*, &+, &-, &**, etc. I have lots of Rosetta Code examples to show these issues.

Real World OOP Examples
Particularly, the differences between Ruby’s and Crystals’ semantics and structure. When to use Structs vs Class, and explanations of getters and property. I still don’t know most of these, as I haven’t done allot of OOP in Crystal yet.

Parallelism/Concurrency
Clear explanations and examples of using Crystal concurrency semantics would be very helpful/essential for users to hit the ground running. This was another area I experienced frustration with getting code working for.

Also, I know Crystal currently doesn’t do true parallelism, but some roadmap toward it (it’s coming, right?) would be helpful for users to asses Crystal’s viability for such use cases.

Summary
The essence of what I’m saying is, useful for users (vs developers/designers) documentation needs to show/explain how to (idiomatically) use the language to solve real world problems that most of its users will confront. Anybody can read a manual of a list of methods, classes, etc, but if you have no idea of how/why you’d ever use these things that kind of documentation has little application meaning.

We have lots of examples from Rosetta Code, and other repositories, to show how to solve different problems in different ways, and seeing these are the most helpful to the average user.

I also agree, the use of interactive learning structures/platforms will induce users to try stuff first, before resorting to asking questions on the forums, if they can get immediate useful feedback, especially when they make mistakes.

I have allot more ideas, but I’ll stop here for the moment.

6 Likes

I have published a draft PR at Add first tutorial lessons by straight-shoota · Pull Request #484 · crystal-lang/crystal-book · GitHub and would love to get some feedback on that.

3 Likes

Thanks for your input @jzakiya, I think all of your proposals are great and important.

I’ve added a sketch for an advanced course to the comment with the outline, and also adapted it to the current state of the draft PR.

2 Likes

Another thing I just thought of, having just done it for a new project, are detailed examples of how to compile/run programs, and how to identify and install shards.

Especially for people coming from dynamic languages (Ruby, Python, etc) where you can just run code in a repl, you have to go thru a number of steps to run Crystal source code.

So we should clearly go thru the steps of running Crystal source code.
How to use the compiler options, how/when/where to use shards, how to setup a shard.yml file, etc.

These things may be second nature to a regular Crystal user, but seem like magic to someone never having to compile a program, and use the command line.

Also, here’s another learning site you may find some inspiration from.

3 Likes

The first lessons are published at Basics - Crystal

9 Likes

Nice simple tutorial ui! :slight_smile:

Please update the Crystal version; currently Compiled with crystal 0.36.1.

It’s using https://carc.in for the snippets. It’s a separate service, and it hasn’t been updated to 1.0 yet. So there’s nothing for @straight-shoota to do here.

1 Like

I’ve done a brief run-through of the tutorial. There is one immediately obvious issue: the Number Methods example in the Math section fails with an error in Crystal 0.36.1, as well as in Crystal 1.0.0. This is due to the gcd method being called with the wrong number of arguments (zero, when there should be one). The example code is 10.gcd. It should be something like 10.gcd(16) (or potentially any integer in place of the 16). The syntax 10.gcd 16 also works, but !p prints it as 10.gcd(16) anyway.

3 Likes

Thanks. Fix is on the way: Fix gcd example call by straight-shoota · Pull Request #494 · crystal-lang/crystal-book · GitHub

1 Like

Good work thanks @straight-shoota

Hello,
thanks for the great start on tutorial.
I’ve just followed it and so far so good.
What’s missing is I’m expecting to see any kind of for/while loop in the tutorial, coming from other language (Python), that is part of control flow (4. More Control Flow Tools — Python 3.12.1 documentation). Or in Go tour A Tour of Go, it’s even before if/else.
I don’t know Ruby, but for starting using any language, I would want to able do loop, I believe the tutorial is not “done”, but stop after knowing do loop would help keeping me writing more useful Crystal.

I see the chapter description says:

  • [Control Flow] – How to structure a program with conditionals and loops

Seems something missed there.

1 Like

Thanks for reporting that. The loops part of the control flow lesson is actually missing and the description is misguiding.
I think I stopped at that point because I wasn’t sure about structuring. Loops in Crystal are closely related to collections and that’s a big topic to start on.

1 Like