(Docs) Shorten Introduction on "Tour of OCaml" and Mention Double Semicolon

[sabine]

The introduction on https://ocaml.org/docs/tour-of-ocaml needs to

1. be shortened
2. say (briefly!) what a REPL or toplevel is, and
3. mention why ;; needs to be used.

The corresponding document is https://github.com/ocaml/ocaml.org/blob/main/data/tutorials/getting-started/1_01_a_tour_of_ocaml.md

[kephas]

How much do you think it should be shortened?

[cuihtlauac]

I don't believe length is such a big issue.

• Tour of Scala: 5118 lines of markdown
• Swift Tour: 2561 lines of markdown
• Tour of Kotlin: 2315 lines of markdown
• Tour of Rust: 2099 lines of yaml
• Tour of Go: 1934 lines of go
• Tour of OCaml: 762 lines of markdown

[Alfredo-Carlon]

Hi, I think I can write a proposal about ;; and what REPL is. While I'm at it, I can also help with some minor clarity issues in the text, e.g. "shows you how to write OCaml files, how to compile them, and how to kickstart a project." transformed to "shows you to write and compile OCaml files and how to kickstart a project" which may have the side effect of shorten the text.

I think that compared to the other tours, this one is on the right track but there is room for improvement, e.g. stating the goal of the Tour on the first paragraph, etc.
I'm happy to help out :)

[cuihtlauac]

Thanks @kephas and @Alfredo-Carlon. There's always room for improvement; anybody is always welcome to make shortening or clarifying contributions. Please do.

There may have been a misunderstanding. I was referring to “Tour of OCaml” overall length whilst @sabine seems to have been referring to its introduction paragraph, and @Alfredo-Carlon seem to be referring to its conclusion paragraph.

To be fair, the OCaml full tour is “Tour of OCaml” + “Your First OCaml Program” which is 762 + 410 = 1172.

In all cases, we're happy to read any proposal from anybody.

[sabine]

Yes, there's no problem with the length of the document in its entirety.

I am only talking about the introduction at the very top of the document. It is longer than necessary and repetitive on mentioning the REPL but it does not address the three points that user testing has identified to be missing.

ETA: Indeed, editing on the documentation to help improve clarity is always welcome and we are happy to review such PRs! ✨

[Alfredo-Carlon]

Super @cuihtlauac and @sabine A pull request is up for just the Introduction, REPL and ;;. Once we are done with these I think I'll move on deeper into the text. I'm particularly interested in the overall idea of the tour and some clarity details etc but probably it is better to open a separate issue.