A Tour of Crystal

[straight-shoota]

Before I came to Crystal, I had a brief encounter with Go and I really enjoyed their guided interactive tutorial A Tour of Go to help newcomers familiarize themselves with the language.

There should be something like that for Crystal, too!

The technical part should not be too complicated, the playground already has most of the functionality for interactive coding and it could easily be integrated into an HTML site with the tutorial texts and example code. A static site would probably be sufficient for that.

Creating a great tour guide will be much more challenging (as everything with documentation... 😄 ). The Gitbook offers a good starting point, and the Go tour could be a guide, as well as similar resources (I've found https://www.learnrubyonline.org/ so far, which also exists for some other languages).

[faultyserver]

http://tryruby.org/ is another great one that I have shown to multiple people to get them started with Ruby (and even programming in general).

Also, it'd be nice if it didn't look like a page thrown together in Microsoft FrontPage :)

[mverzilli]

I think it's a great idea and I'd say go for it! Count on us to link it from crystal-lang.org once it begins shaping up, setting a subdomain for it, etc

[straight-shoota]

I just stumbled upon https://github.com/crystal-lang/crystal-presents which has the technical foundation already covered! And looks pretty nice, too, @bcardiff

[ghost]

a very good "tour" for me was the ruby koans these could probably relatively easily be transferred to crystal although I do not know how much they depend on rake specifics (nothing prevents crystal from using ruby rake though)

EDIT:
fwiw the best documentation I have seen so fare is the one from node.js where many parts have real descriptions of different approaches pro/con arguments, which I find really helpful for not getting lost in options/ missing options

[donovanglover]

What's the status of this? I'd like to try making an interactive tour of Crystal. I've always loved the "learn by doing" philosophy and wouldn't mind contributing here.

[asterite]

Please go ahead. Once you finish, let us know and we'll link it in the wiki or official site.

[marksiemers]

@gloverdonovan - For a beginning outline, the talk that @asterite gave (maybe a year or two ago) would be a good starting point. I have lost the link to the video, but I'm sure someone has it or maybe @asterite can provide the slides or code used for the presentation.

[donovanglover]

@marksiemers Thanks for the reply. I plan to have one main idea covered in each section, such as a section on modules and another on classes, each with their own individual subsections / exercises. A link to the video would be great; I'd appreciate some help on an outline.

I want to try test-driven learning (i.e. run a spec file every time someone submits their code) so that end-users can see exactly how their code behaves when given a few test cases.

One roadblock for me though is that the crystal playground isn't sandboxed by default (i.e. you can access system files, etc.). I'm not sure how I'd fix this for a production server.

[donovanglover]

Did some testing and it looks like the Crystal play website uses playpen to sandbox things. How reliable has this been so far, and is there any reason to prefer playpen over firejail?

[marksiemers]

Here is the video: https://vimeo.com/191351066

He gives some background before jumping into the language features.

Starting around 10:30, Ary gives a walkthrough of the language.

[RX14]

I want to try test-driven learning (i.e. run a spec file every time someone submits their code) so that end-users can see exactly how their code behaves when given a few test cases.

we have https://play.crystal-lang.org/

[straight-shoota]

The source for that is at https://github.com/jhass/carc.in and it uses playpen, as @gloverdonovan already mentioned.
I'm sure we can find a way to either run the Playground in a sandboxed environment as well - or just simply use carc.in as a backend for a publicly hosted playground.

In fact, the technical implementation is really not important right now. The main issue is putting together great content.

For now, we can just use the playground as is and only run it locally.

[marksiemers]

I agree with @straight-shoota, getting the content together should be the highest priority - even if that means only running locally (similar to running go's tour locally).

In the future, I like some of the features that a local Crystal play server provides over carc.in

• Showing the variable values and types for each line of code
• Having a modal window for loops, so you can see what happened for each iteration

I also like the workbook functionality, but I think that is not as applicable to an online version unless crystal wants to build their own repl.it

[RX14]

The content should largely be written long-form tutorials.

If there is a walkthrough interactive thingy it should come after the "book-style" thing. Long-form text is one thing everyone can agree on, I know that I would skip any interactive tutorials I found and search for an introductory text. Others are different but the basics please first.

[girng]

I've done a lot of programming tutorials online, but just want to say I really enjoyed Haskell's. The words they use make the experience ten times better and increase the developer's confidence (which inherently increases the developer's learning ability).

Examples:

• First Time's a Charm
• Well done, you typed it perfect!
• Hi there, chris! That's a pretty name. Honest. You're getting the hang of this!
• Great, you made a list of numbers! If you win we'll split the winnings, right?

I'm not saying we need to have this exact level of happiness during an interactive tour, but I just want to iterate words of encouragement can really make a difference.

[dainmiller]

I would love to work on this!

[straight-shoota]

Great, feel free to check out current progress on https://forum.crystal-lang.org/t/interactive-tutorial/3019 and crystal-lang/crystal-book#484