Walking through docs from "LEARN" link is clunky

[marksiemers]

For a new user of crystal, if they goto the website and click "LEARN", they are taken to this page: https://crystal-lang.org/docs/overview/

The flow of pages from there is:

• Overview - basically how to read the code samples, and suggesting jumping through the docs
• Hello World! - A hello world puts statement with some explanation
• HTTP Server - A short walk-through creating a basic HTTP server
• Syntax and Semantics - "The program’s source code must be encoded in UTF-8."
• Comments - Description of how code comments work
• Literals - "Several literals are available for creating many basic types in the language."
• Nil - Short explanation of nil
• Bool - Short explanation of bool
• Integers - Detailed explanation of Integers
• Float, etc. The data types with detailed explanations continue from there

There are a few ways this could be improved. It may be that "LEARN" links somewhere else, instead of changing crystal-book itself or these changes may improve the experience:

• The order could be improved, the user goes from `puts "Hello World!" straight to an HTTP server (a bit "How to draw an Owl"-like).
• Some pages (e.g. "Syntax and Semantics") are one or two sentences and could be combined.
• Summaries of all the listed data types could be provided on one page, then details linked from there.

It may be best to have a different place for "LEARN" that is more tutorial style, similar to https://tour.golang.org

Until that can happen, perhaps improving the flow for this part of the guides is low-hanging fruit.

[straight-shoota]

There are a lot of things needing improvement. I've just yesterday started to work on a slight reordering and reorganizing of these pages, including improvements to the Syntax and Semantics page. PR will follow.

The Overview page should obviously be edited, especially if it (currently) serves as an entry page for learning Crystal. But I agree that this is not the best solution, there should be a dedicated tutorial for this which is not integrated into the language reference. I have proposed this in crystal-lang/crystal#4462

[RX14]

I think we need to further clarify that this is the language reference and as such it's a reference manual, not something meant to be read in order necessarily. We need tutorial-style walkthroughs and tours of the language but they should be in a different place that we need to create and work on. Having the community write/brainstorm these tutorials would be a great idea.

[marksiemers]

@RX14 - Agreed that this is not an ideal solution nor a long-term one. I think the build-out of tutorial-style walkthroughs will take an unknown amount of time, but likely at least a few months - assuming some people in the community have time to dedicate to it.

It should be clear that the docs/reference are not meant to be read in order as well.

I think (for now) having just the Overview and Examples section that should be read in order will be quicker to implement than a full separate tutorial system.

In the future, I think having a crystal play server adapted to give a "tour" could be the way to go. A better Overview and Examples section now could be used as an outline or starting point for that.

[straight-shoota]

This issue is somewhat obsolete (#384 and crystal-lang/crystal#4462) are probably most adequate successors.