Proposal: reworking of Learn section of ocaml.org

[johnwhitington]

I have been asked by the OCaml Software Foundation https://ocaml-sf.org to spend a few hours on a proposal to refresh the Learn section of the OCaml website. To be clear, the few hours time for thinking about it and writing this document has been funded; the time taken to actually do the work relies upon some version of this proposal being accepted.

I feel it's important that the people who know most about ocaml.org, that is to say you, get a good look at this proposal early on so you can tell me if I am on the wrong track, or to add proposals of your own. (Next week I shall have another for you, on how to improve documentation on setting up one's OCaml environment; that one, by contrast, has been funded to completion).

Introduction

Official or semi-official programming language websites like ocaml.org tend to have a prominent page or pages providing a whirlwind tour of the language's possibilities, or a fast-paced tutorial, or a full from-the-beginning tutorial, or some combination of all three of these things.

What are the purposes of this content? They are two:

• to persuade visitors to the website to download and try the language, by showing off its capabilities
• to educate the beginner once they have downloaded and are trying the language for the first few times. (Later on, they might move to a more complete tutorial on the same or another website, or use a free or paid-for book, but this does not remove the need for such content.)

It follows that such content should be accessible, appropriately targeted, accurate, easy to navigate and up to date.

NOTE: It is important to differentiate this content from `How to set up your environment', which ocaml.org and most other languages have too, and which is another kind of required introductory document. I will have a separate proposal on this soon.

Current ocaml.org content

The ocaml.org website distinguishes on the main menu between Learn and Documentation. This is a useful distinction, and we would wish broadly to keep it. Here we are interested in the `Learn' part.

• Learn --> What is OCaml? https://ocaml.org/learn/description.html

• Learn --> OCaml tutorials https://ocaml.org/learn/tutorials/

• Learn --> Code examples https://ocaml.org/learn/taste.html

• On Ocaml.org but marked as too opinionated https://ocaml.org/learn/tutorials/get_up_and_running.html

Not on ocaml.org: https://github.com/ocaml-community/awesome-ocaml. Other examples?

How other language communities do it -- Haskell

• Main content on the Haskell wiki https://wiki.haskell.org/Haskell

• ``Haskell Features'' at the bottom of main page on https://www.haskell.org

• The what is Haskell and why should you use it? https://www.haskell.org

• Documentation page https://www.haskell.org/documentation/ links to other documentation elsewhere.

How other language communities do it -- Python

Python seems large enough that most of the content is external, and not even on the python.org page!

• main site https://python.org no docs, put points to wiki

• https://wiki.python.org/moin/BeginnersGuide which again points to external options

• selling the language, explicitly: https://wiki.python.org/moin/BeginnersGuide/Overview

• https://wiki.python.org/moin/SimplePrograms A short but pleasant simple examples page

How other language communities do it -- Go

• A Tour of Go, available interactively online, or offline through Go itself: https://tour.golang.org/welcome/1

• Main documentation page: https://golang.org/doc/#articles

• How to Write Go Code (introduces build and packaging): https://golang.org/doc/code.html

• Codewalks: guided tour of Go Programs e.g https://golang.org/doc/codewalk/functions/

How other language communities do it -- Rust

Very impressive range of official documentation:

• Main site: https://rust-lang.org

• Their own book: https://doc.rust-lang.org/book/

• Tutorial for the complete beginner, linked from main website and blessed as official: https://github.com/rust-lang/rustlings/

• A second official book, Rust by Example, is a tutorial and exercises, in order: https://doc.rust-lang.org/stable/rust-by-example/

And much much more: https://www.rust-lang.org/learn

Concerns

Here are some examples of concerns that ocaml.org's own authors and some bug-submitters have expressed. I list them to help us understand what to fix, not as a criticism of my own.

• From the website itself: ``Many of the tutorials below need updating and tutorials on many new topics are needed.''

• https://github.com/ocaml/ocaml.org/issues/824 Many tutorial-related suggestions for improvement

• https://github.com/ocaml/ocaml.org/issues/1091 Tutorial on streams still online but not working

• https://github.com/ocaml/ocaml.org/issues/1038 Beginner confusion over CamlP4

• https://github.com/ocaml/ocaml.org/issues/627 A potentially misleading tutorial

• https://github.com/ocaml/ocaml.org/issues/933 Possibility of interactive workbook described

Here is a previous thread on fixing the tutorials: https://github.com/ocaml/ocaml.org/issues/996

Proposal

I propose to secure the existing content, so to begin by:

• checking everything in the current website works technically, fixing anything which is still relevant but currently broken;

• pruning out of date or deprecated information, and relegate information which is useful but only for a tiny number of people;

• ensuring consistency of tools used, words used, example format, language; and

• making sure everything works on all platforms, including Windows, or annotate where it does not.

And then go on to:

• write ``A Tour of OCaml'' (by reusing existing content and adding to it);

• rework the tutorial substantially by adding to it and rearranging it to be more cohesive -- this is in addition to the fixes to the tutorial mentioned above.

  • make sure we are clear on what is required for all this content. What just needs OCaml. What needs OPAM? What relies on Utop not just the basic top level? Minimize the dependencies as much as possible. We need to talk about these modern `platform' tools without forcing them on people.

NOTE: What to do about translations? Mostly it is just translations of topic headings it seems, not the main content? Contact previous translators? Try to keep as much as we can?

[sanette]

I think this is a most useful work you're undertaking. Thanks!

Concerning the separation between learn/documentation, we have to remember that the manual has its own "tutorial" chapters

[avsm]

John, thanks for starting off this discussion and for your proposal to rework the learning section. This is timely and important given the rapid release rate of OCaml over the past few years. A few high-level notes first:

• Going through the website and removing unsupported tools (e.g. like camlp4) would immediately be sueful. That would be great to do at a high priority.

• From an infrastructure perspective, my preference for ocaml.org is to make the main website as lean and simple as possible, and move some domain-specific content into a subdomain. An OCaml tutorial seems perfect to move to a domain such as "learn.ocaml.org", where we could deploy an interactive jsoo-based toplevel environment so that users can actually interact with the language in their browser. We have several such prototypes over the years, but never a push to move it under ocaml.org. Would you consider looking into what such a toplevel environment could look like while going through and porting the comments?

• In terms of ongoing maintenance, it's essential that examples are type checked at compile time. The modern version that we're supporting across several projects is now https://github.com/realworldocaml/mdx, which is also used in production in RWOv2. I'd recommend replacing the current ocaml.org use of otool with mdx. It should also be possible to run this under CI more easily to test Windows.

• I think in the first instance, the scope of this content should be for the core language itself, and not involve opam beyond the minimum requirements to get installed. I'll talk separately about the Platform tools in #1137.

• Translations: it's fine for them to lag behind, but with a major overhaul we just have to contact them all and request a burst of work where possible to keep in sync.

Finally, it would be worth having a video call organised to quickly go over some of these ideas when they become a bit more baked, and post the minutes here. August is a poor month for that, but early September could work.

[johnwhitington]

• Going through the website and removing unsupported tools (e.g. like camlp4) would immediately be sueful. That would be great to do at a high priority.

Gone, or almost completely, in https://github.com/ocaml/ocaml.org/pull/1147

[ghost]

I would survey scala, clojure, kotlin, elm as well, when glancing at other communities.

I had thought about this topic a bit and felt that teach.ocaml.org should be separated out as well, and I noticed kotlin also creates a section for teach.

EDIT: moved rest of content to its own issue

[ghost]

checking everything in the current website works technically, fixing anything which is still relevant but currently broken;

pruning out of date or deprecated information, and relegate information which is useful but only for a tiny number of people;

This will be a recurring problem, as ocaml style and base libraries will keep slowly evolving. Some have proposed compiler checks of the source to make sure its accurate. That's a good start, but I think crowdsourcing this content every ~6 months will probably result in more engaging and fresher content. I would do it as follows:

1. Every six months, pick ~4 problems in the style of advent of code or hackerrank warm up exercises, that are relatively simple and overlap with topics we want covered for beginners. Post the call for submissions on discuss.ocaml.org. Have people submit their solutions via gist links.
2. Have one content admin read through the submissions and pick the top five best answers
3. Copy those answers to the ocaml website.

[johnwhitington]

(Closed because the work involved has been (mostly) done)