Help revamping the getting started tutorials in ocaml.org

Learning
1

This is a call for feedback and collaboration.

With the help of many, but mostly @sabine, @professor.rose and @tmattio, I’ve attempted to revamp two of the “getting started” tutorials from ocaml.org. I’d love to extend the length of that list.

This PR contains the state of this work: https://github.com/ocaml/ocaml.org/pull/1431

In our opinion, the getting started tutorials should include three mandatory tutorials

  1. Install
  2. A Tour of OCaml
  3. How to Write an OCaml Program

The fourth, dealing with installation options on Windows, being optional for apparent reasons.

This series of tutorials are intended to have a wide audience, especially for newcomers to OCaml. That’s why we believe in community feedback to make them as good as possible to most people. OCaml is currently trending in many conversations. This is a prime opportunity to ride that wave of interest.

This PR only covers parts 2 & 3 because they were mostly written from scratch. We’re also working on an update of the Install tutorial, but since it is not a rewrite, it felt more natural to put it in a separate PR. Although it is not a draft, I must say that this is an early version of the texts. I hope you will understand.

Here is the primary learning idea. That’s a breadth-first traversal of the rabbit holes.

A Tour of OCaml provides an overview of the basic language features. Here, the goal is not to address more topics but to reduce to the core of what can be learnt fast; only using UTop, will always be useful later and helps build an overall view of OCaml.

How to Write an OCaml Program has the same approach, except instead of using Utop, the reader should write files and command lines. It’s a compiler story, while the previous one was an interpreter story.

It is early August. In the northern hemisphere, we should enjoy the sea, the mountains, our friends or culture. I will be hiking during the next two weeks (and reading Martha Wells Murderbot Diaries).

I’d love to include your feedback when I get back.

7 Likes
2

Hey everyone, it will be really helpful if you critique, and make suggestions how this can be better.

After all, this is what OCaml looks like to the newcomer arriving on OCaml.org.

Here’s what it looks like on the staging site:

https://staging.ocaml.org/docs/a-tour-of-ocaml

and

https://staging.ocaml.org/docs/how-to-write-an-ocaml-program

We care a lot about making this a great experience that helps people fall in love with OCaml.

5 Likes
3

Now that the Tarides break is over and we’re coming to the end of the summer (so people are getting back from their holidays!), we’d love your feedback on these revisions before we push them live on OCaml.org.

I’ve noticed that more people are talking about OCaml on social media! This is a great time to engage more newcomers, also to ensure the OCaml documentation is understandable and updated for them.

Collaboration within the OCaml community is so important!
Looking forward to your comments!

2 Likes
4

The pull request corresponding to these tutorials has been updated with the feedback we’ve received.

We are considering publishing soon but are still accepting feedback.

1 Like
5

“How to write an OCaml program” says:

OCaml comes with both an interpreter and a compiler.

That’s wrong. It comes with multiple compilers, and a bytecode runtime. But it does not come with an interpreter. The bytecode compilers are not interpreters.

3 Likes
6

You are right; this statement is not accurate, it will be updated. Thanks

Here is an updated draft:

By default, OCaml comes with two compilers, one translating sources into native binaries and another turning sources into a bytecode format. OCaml also comes with an interpreter for that bytecode format. Other compilers exist, for instance, js_of_ocaml generates JavaScript. The toplevel uses the bytecode compiler; expressions are read, type-checked, compiled into bytecode and executed. The previous tutorial was interactive only; the toplevel was used. This tutorial gives a glimpse at batch processing only using the native compiler.

1 Like