More upfront examples for simple common tasks

[plainas]

Hey everybody. Impressive work.

Please take this for what it is: a little bit of feedback from a total beginner.

I went through most of the documentation and skimmed a little bit over some API docs. A bit of googling eventually answers most of this things, but I still think a few direct examples could be more prominently shown either in the landing page on in the first sections of the documentation. Perhaps inside a slider like python or nim websites do...?

• Map, filter, find simple examples.
• Simple example of iteration over an iterable
• simple function references usage, assign functions to variables
• simple non-OO strategy pattern example. Assign functions to keys of an hash and call them by key
• Read a file line by line.

NOTE: Can a issue author not label their own issues? Please label this as docs.

[bew]

There are a lot of examples in specific API doc pages, but I agree, it would be great to have a kind of "language overview" for common stuff.

For now the best way to learn is to read others people code (e.g. The Crystal compiler itself), but it surely can be a little disappointing to do that when you just start..

The only issue I ser for this is that as the language is still in alpha, the syntax and the stdlib are not frozen, and we would have to maintain some examples code that is not next to the real code (like the api docs).

But I think this is a minor issue because the language/stdlib won't change a lot now for common stuff..

[asterite]

The language is missing a good tutorial, that's all :-)

[plainas]

@bew Indeed. A lot of juice is in the API docs, although not every library is documented. Many have just a list of methods. I believe it is a work in progress.

@asterite The documentation under 'docs', feels like it is on the right track to become that. Just needs to be a bit expanded. The official introductory documents for python and scala, for example, are similar in both style and length:

• http://docs.scala-lang.org/tutorials/tour/tour-of-scala.html
• https://docs.python.org/3/tutorial/

As a beginner, after reading the docs and most of the api referenec, I feel like I lack the knowledge to do many relatively common things. While the above links will take the beginner a much longer way.

I checked the repository called crystal-by-example. It contains many useful examples, but they lack textual explanations. Would it be possible to include them in the docs?