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.

8 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
7

Thank you. But in fact it comes with at least 6 compilers.

I dunno how to address that, but I strongly recommend making a distinction between the OCaml language and the standard distribution, let’s call it the OCaml SDK

2 Likes
8

For a getting started guide, that is digging into the weeds a bit too much. Here when we say ‘OCaml’ we just mean the standard distribution.

2 Likes
9

I guess the interpreter means a REPL program like ocaml or utop.

From a user perspective they act as interpreters : no need to 1/ compile the program, and then 2/ launch the resulting executable.

10

The “First Steps” section has three tutorials: the first covers installation, the second covers interactive experience, and the last covers compilation. The learning goal of the whole sequence is: there’s an easy way to install, there’s an easy way to get started with the language (utop), and there’s an easy way to start coding “real” projects (dune). Ideally, I would have preferred not to mention bytecode compilation in this tutorial. @Frederic_Loyer is right, when getting started, you don’t need to know the REPL is calling a compiler. A newbie must only know there’s a REPL and a native code compiler.

As usual, this is open source; improved rewrites are highly welcome. Let’s keep in mind that code and tutorials are trade-offs; here, we want to tip the balance towards simplicity rather than exhaustiveness. As long as we’re not telling lies, simplification should be preferred.

1 Like