Crystal: Documentation is confusing for newcomer from "worlds" other than Ruby

[jan-zajic]

I programmed in many languages, but not in Ruby. So i have to rely on Ruby documentation, because Crystal doc is currently little bit confusing for newcomers.

During reading book at http://crystal-lang.org/docs again and again, when coding and searching for some help, I still can't help feeling like many parts of it expects some previous knowledge of programming in Ruby. Some things are just missing and i must read Ruby documentation or books about Ruby so that the moment comes when i say: I see! This is how it works / it is meant.

Other place when i search help is api doc at https://crystal-lang.org/api, which looks unfinished / incomplete, so i also often have to search in Ruby API docs, to make sure how things are likely to work and then search in the sources of Crystal.

Please do not take this as criticism, i try to background introduce myself and my future effort that i want invest to help you with this. So i want to focus on adding missing things for others, until i forget how i started with Crystal. It's not a problem for me, but I would like to help others, especially to real beginners to programming, because Crystal is an excellent language and deserves it.

I would one day be able to recommend, for example to students at university, Crystal as their first language without the need to learn Ruby first.

I also think the diversity that programmers from other worlds (for example I'm primarily Java Guy) will bring can bring a lot of good for Crystal language and libraries design, and for whole Crystal community.

[straight-shoota]

Yes, we're still missing lot's of documentation. Yet for some reason, many Crystal developers still manage to get around. I don't know if this is just because of Ruby background. There are also many differences to Ruby...

Anyway, it's great that you're willing to help! Especially people who are new to the language have a fresh view on things and what documentation is needed the most. Thanks for that!
If you can't write documentation for something yourself but think that it's important to document, don't hesitate to open issue asking someone else to do it.

[RX14]

I still can't help feeling like many parts of it expects some previous knowledge of programming in Ruby.

This is a well known issue! However, since it's very difficult for us - who already know the language - to figure out what's missing we really really need the community's help to address this issue. If you have to look something up in ruby docs bcause you don't understand it, please make an issue, or a comment on this issue to let us know. We can then work together on improving the documentation!