Feedback on ocaml.org's tutorials for beginners


#1

Hello, I was trying to learn ocaml from tutorials on this site. I think they are designed badly and here are some reasons.
Why are there always comparisons with C or Java? This is supposed to be a tutorial for beginners.
Why are there always some new concepts introduced but not explained? Take a look on this example: https://ocaml.org/learn/tutorials/structure_of_ocaml_programs.html#The-sequence-operator. There is a code example only to show that OCaml is powerful instead of explaining what ; operator does (what fun or -> or _ is not clear yet). And then there is a side-note about + operator and that it can be used as a function and ; can not. But I still want to know more about ; operator!
At the same time, there are such inaccuracies like placing two examples in one listing.


#2

As Alex says in his blog http://blog.nullspace.io/beginners-guide-to-ocaml-beginners-guides.html

The standard OCaml tutorials are now awesome. They used to be non-existent, then they were terrible. Now they are awesome.

You’re right. I learned from this site and sometimes got lost.
But there are many other good books available.
You should play with the language in a Toplevel (REPL), looking at books, at stdlib refman (or whatever replacement lib), at tutorials to get some material to play with (functions, code snippets, tutorials…).
But write code, and evaluate it in the REPL to get a good understanding of the language.

You are also very welcome to suggest any improvement to ocaml.org


#3

I believe the ; explanation is fairly clear: ‘The semi-colon ; may be seen as having type unit -> 'b -> 'b — it takes two values and simply returns the second one, the first expression is guaranteed to be evaluated before the second.’ However it is true that it’s pretty long-winded and compares to C too much. As well as the code example being unnecessarily complex. Also the motivation is missing–i.e. why does ; sequence operator exist in the first place–why would I want to use it.

If you would like to send a documentation cleanup for anything btw–doesn’t need to be for this–the pencil icon on the top-right corner of the page will take you to the corresponding file in GitHub which you can then edit using the GitHub UI (it will fork the repo for you and put your edit on a branch for sending as a PR). I’m sure it would be much appreciated.


#4

Yes, explanation is pretty clear but example doesn’t try to expand it.

I don’t know who is in the charge of language development but when I tried to learn the new language and opened the first link in Google, I had some difficulties. And since I have some experience with other languages, I can understand what tutorial’s author wanted to say. But many people won’t. So, I decided that it might be good for the community to have some feedback on the tutorials.
P. S. Sorry if I don’t reply - I am not really interested in conversation.


#5

Yes, the tutorial overall could be perhaps designed and explained better. However it is all open source so the hope is that people will contribute to it if they can.

Generally when you offer feedback to OSS you would expect to have at least some amount of back-and-forth about it :wink: It’s fine if you don’t want to engage, lots of people don’t, but I think it’s the norm.


#6

:rofl:
Sure that using such a search tool that way won’t lead you very far (personal opinion).


#7

AFAIK, the tutorials page on ocaml.org was originally separate blog posts from the community that was aggregated in one page.

There was an attempt to reorganize the pages (particularly the table of contents) so that it gives somewhat a structured ordering of things, but given that there was no big design of the contents in the first place, it still lacks the coherence from one article to another.

I think that the OCaml manual would be the best place to start if you’re looking for a step by step introduction to the language, but even then, it’s (rightfully) missing information some popular community tools such as opam and dune.