You started to learn OCaml less than 12 months ago? Please help us with our user survey on the OCaml.org Learning Area

Community
,
1

We’re asking specifically for you, if your experience of learning OCaml is still ongoing or so recent that you still remember

  1. what you struggled with (or still feel like you’re struggling),
  2. how the current materials failed you,
  3. what other materials helped you understand.

if you have previous experience in other languages, we also find it highly interesting to learn about resources that you found particularly effective/engaging/educational and why you think they are particularly great.

Our goal is to improve the “Learn” area of OCaml.org - and this is a pretty broad topic in the sense that we want to provide a framework on OCaml.org where content is organised properly in such a way that information is easy to find and effective to use for various people with different backgrounds and learning styles.

The survey is here. (Removed the link as the survey is closed.)

If you indicate you’re available for interview, our UX designer Claire may contact you to schedule a video call with you.

There will be a summary of the points brought up no later than May 5 in this thread.

14 Likes
2

Here’s the promised update on what kind of feedback we got out of the survey.

We distributed the survey (1) here on the OCaml Discuss, and (2) on the OCaml Discord server. The survey was also shared via (3) LinkedIn, (4) Twitter, and possibly more channels. We asked newcomers to OCaml to participate.

57 people responded to the survey and we had to close the survey early so that we have the capacity to properly analyze and categorize all feedback.

Invites have been sent out by Claire to the participants who volunteered to be interviewed.

We have found last time that the interviews helped us understand the status quo and the potential improvements from the community’s varied perspectives much better than we did only from the survey. I feel this has been a critical factor to enable us to change things for the better.

So thank you for taking the time to help us! :camel:

Statistics

You are…

  • 50.9% an employee

  • 24.6% a student

  • 12.3% self-employed

  • 12.2% other

How would you define your programming skills?

  • 47.4% experience in both functional and imperative programming languages

  • 44.4% experience in imperative programming languages

  • 8.8% experience in functional programming languages

  • 3.5% complete beginner

Where did you learn programming?

(Answers only from people who did not identify as “complete beginner”, multiple answers possible)

  • 75.9% in my free time

  • 70.5% at university / school

  • 44.4% at work

Which programming language(s) do you use and how would you rate your skills?

(People were free to answer this to the extent they wanted to in a text field)

Language Beginner Intermediate Advanced Level not specified Total
OCaml 12 6 1 2 21
JavaScript 1 5 9 2 17
Python 2 6 7 1 16
Rust 5 6 1 1 13
C 0 6 3 1 10
C++ 1 4 2 2 9
Java 1 4 3 1 9
Haskell 3 3 1 1 8
Go 0 6 1 0 7
TypeScript 0 1 6 0 7
Clojure 1 1 1 1 4
ReScript 0 3 0 1 4
Scheme 2 2 0 0 4
Ruby 1 2 0 0 3
Kotlin 0 1 1 1 3
Emacs Lisp 2 0 1 0 3
PhP 0 1 1 0 2
Coq 1 0 0 0 1
Elixir 0 0 1 0 1
F 1 0 0 0 1
Prolog 1 0 0 0 1
Swift 0 1 0 0 1
F# 1 0 0 0 1
Scala 0 1 0 0 1
Elm 0 1 0 0 1
Lua 0 1 0 0 1
Julia 0 1 0 0 1
R 0 1 0 0 1
APL 1 0 0 0 1
Scala 0 0 0 1 1
Mercury 1 0 0 0 1

What occasion made you start to learn the OCaml programming languages?

  • 57.9% personal reason

  • 31.6% professional reason

  • 10.5% other (University, Outreachy/internships, wanting to practice a different programming paradigm)

Which of these do you prefer to do?

  • 47.4% Learn by both completing exercises and do small / personal projects

  • 42.1% Learn with small / personal projects

  • 5.3% Learn with exercises

Which kinds of resources do you use?

(multiple answers possible)

  • 70.2% search online

  • 66.7% books

  • 56.1% Language tutorials in the OCaml.org Learn section

  • 56.1% tutorials / blog posts on other sites

  • 50.9% ask on forums / communities (Discuss, Discord, Reddit…)

  • 45.6% OCaml videos

  • 33.3% exercises on OCaml.org

  • 33.3% exercises on other sites

  • 24.6% ask friends or colleagues

  • 19.3% the OCaml Playground

Insights

1. Learn Homepage

  • Papers should be moved to a less prominent position:

Multiple respondents bring up the point that papers are not particularly relevant for OCaml newcomers, thus, they should be moved to make room for more relevant/engaging content.

  • Books should be moved up to be more visible: A high percentage of users reports using books to learn, so making books more visible would be helpful.

  • Display of books should be improved:

Books should be categorised by target audience / topic depth (beginner, intermediate and advanced) and it would be helpful to show which books are accessible online for free.

  • Releases are not relevant in the learn section: It would be better to present releases on the main home page and/or in a dedicated section.

  • There are existing tutorials in the OCaml language manual which could be showcased: E.g. the tutorial on parallelism

  • A section highlighting OCaml courses (free or paid) could be added

  • The top three big links on the page are so big and stand out so much that they resemble advertisement placement: They should be reworked to look part of the site UI and take up less space so we can see more content.

Rust is often cited as an example of how to structure documentation well:

  • organised into dedicated sections that deep-dive into certain topics

  • sections that dive into top use cases

2. Left Navigation Structure in the Learn area

  • Sections should be rearranged and combined because the sidebar is too tall - we can’t see everything without scrolling

  • “Learn OCaml” link is unnecessary as it’s reachable from the top navigation bar

  • “Exercise” and “Language manual” are redundant between left hand side navigation and main content

Our take-away from this is that the overall navigation within the Learn area needs to be overhauled from an information architecture perspective.

3. Requests for New Content

3.a Dune and Opam Tutorials (High Priority)

Multiple people bring up that their one biggest request for new documentation is to have tutorials regarding how to get started using dune and opam in a project-based learning workflow. The dune documentation is perceived as comprehensive and detailed, but people are instead looking for quickstart tutorials from a practical perspective so they can get started working on their projects.

Topics to cover:

  • How to set up a dune project

  • How to expose and import modules

  • How to add dependencies to a dune project

  • How to use opam lock files

  • Possibly: How to work with local opam switches

3.b Tutorials on Real-World Topics

An often requested format is project-based tutorials that one can follow along step by step.

Mentioned topics:

  • Web: how to make HTTP requests, how to set up a simple HTTP server,

  • Compiling OCaml to JavaScript

  • How to write a command-line tool?

  • How to debug print in OCaml?

  • Intermediate tutorial: Concurrency with Lwt/Eio

4. Problems With Existing Content

  • Get Up and Running is too long: The instructions are very long, and there is not even a code example in this tutorial.

  • Some tutorials need better explanations and examples as they are sometimes too terse.

  • Some tutorials make comparisons with other languages like Perl or C which are not necessarily part of common knowledge these days.

5. Feature Requests

Interactive Tutorials and Examples

  • Ability to try out examples from the tutorials interactively.

  • Have an interactive tutorial integrated with the OCaml Playground.

  • Make it possibly to solve exercises in the playground and have solutions be automatically graded.

Bring back the OCaml Planet in a modern format in the Learn area

  • aggregate feeds from blogs that post useful content for learning OCaml

  • also aggregate videos

Add video content to the Learn area

  • link or embed relevant videos in the tutorials

6. Resources Recommended

We asked respondents to tell us about resources the would recommend, and also about resources for other programming languages that they find particularly useful.

Resources recommended for learning OCaml:

Resources in other languages that are mentioned:

7. Other Requests and Suggestions

Home page

  • Add a big nice button to “Download” OCaml

  • Change wording CTA, confusion with “Get started” and “Learn OCaml”.

Accessibility

  • color contrast

  • dark mode / light mode

General

  • Make code that is intended to be pasted into a REPL more visually distinct from example code that is intended to be used in other ways.

  • offer multiple language French/English/…

  • OCaml should be advertised more as a general purpose language, reputation is currently perceived as being “a domain specific language for compilers and interpreteres”

There is a lot of actionable feedback in here and you can expect to see changes to the Learn area in the next weeks. :slight_smile:

15 Likes
3

Reflects the inherent complexity of installing OCaml:

  • Install your OS’s dev tools to get a C compiler toolchain
  • Install opam
  • Initialize opam
  • Activate a switch
  • Install dune, ocaml-lsp-server, and other stuff in the switch
  • Finally, create a new project directory probably with dune
  • Enter the directory and do an initial build

Ideal workflow:

  • Download a (hopefully small) installer
  • Run the installer
  • The installer sets up everything (dev tools, opam, switch, dune, LSP, etc.)–hopefully quickly
  • Create a new project
  • Enter directory and do initial build

This will definitely take a lot of work :slight_smile:

1 Like
4

This will definitely take a lot of work

But that’s not the only downside. It will also take a lot of control out the user’s hands, unless you take a lot of care to provide options in the installer CLI to tweak everything. And once you do that, the single installer doesn’t seem so much simpler than the current steps anymore.

5

The question is who the ‘up and running’ instructions are targeting. If it’s newcomers then I would argue a simplified automated install is better. If it’s power users then we can leave it as is.

6

One worth linking ressource is GitHub - ocaml-community/awesome-ocaml: A curated collection of awesome OCaml tools, frameworks, libraries and articles. There are many ressources (a sorted and commented list of well sorted packages), and it can be useful for any serious project.

1 Like
7

Installing wasn’t bad really, the notes I made when getting started looked like:

brew install ocaml opam
ocaml --version
cd new-project-dir
opam switch create . <ocaml version>

The part that slightly bugs me is having to remember to install the LSP again for each new project before VS Code will work properly (and dune too I guess) …so far OCaml is the only language I’ve worked with where that is the case

8

Several things missing here.

  • There’s no need to install ocaml separately with brew if we are installing it with opam, in fact they might conflict
  • Need to run opam init
  • Need to install dune and other dev tools, as you noted about LSP
  • Need to set up the project with correct dune init invocation (need to look that up with dune init --help and trawl through man page)
  • Tell editor e.g. VSCode where current project’s environment is
  • Need to do initial build before LSP features can kick in

It looks simple if you leave out all this :slight_smile:

1 Like
9

How does dune require LSP ? Rhetorical question; it doesn’t. Or did you mean installing dune in each sandbox so that VSCode works? That may be; I don’t use VSCode so I don’t know [*0]. But yeah, dune being a separate piece is one part of @yawaramin opinion I agree with, it is unnecessary pain.

[0] I tried hard actually, in part because everyone at $DAYJOB uses it, but I just can’t. Old dog, new tricks.

11

Agreed. It pains me that I lost my notes with timings and exact steps from just two weeks ago. But I started from macVM on an M1, and the overall time took 15 minutes. Just copy-and-paste … no time was allotted for reading and understanding what was happening.

(From memory):

  1. Install xcode
  2. Install brew
  3. Install opam
  4. opam init this was the only interactive command
  5. Install all the Platform tools (dune, lsp, merlin, etc.) into the global switch
2 Likes
12

I don’t think this fair, though. The first two steps will dominate the time, and they are not Ocaml specific.

BTW, I think you really don’t want the full Xcode. Delete it and keep just the command line tools. Otherwise you’ll find you’ll have to download ~10 Gb of completely irrelevant updates every 2 months or so.

13

Yep, I followed exactly what Homebrew tells us to do: install the “Command Line Tools (CLT) for Xcode”. That was reasonably quick!

Actually the first two steps did not dominate the time. If I recall installing brew was just one minute. The most expensive steps were the last two steps.

Aside A: A page that accommodates beginners has to start at the lowest common denominator. It is not a question of fairness but being realistic about the audience. And IMHO it is helpful to tell beginners what is being installed (ex. a C compiler, a system-wide package manager, an OCaml package manager and an OCaml virtual environment with IDE+build tools) and be upfront with basic user-cost metrics (basics: time to read, time to install, time to first Hello World, and how much disk space).

Aside B: If I were in love with Rust, I’d say that installing Rust with rustup does not require 1) a C compiler, or 2) a system-wide package manager, or 3) a separately installed Rust package manager, or 4) an isolated Rust virtual environment. I might even say those four requirements are specific to the standard OCaml toolchain, even while acknowledging 1 and 2 are useful in other contexts.

1 Like
14

Random thoughts:

It is technically feasible (and likely requiring only a reasonable amount of engineering) to simplify the setup process for new comers as

  1. install/start vscode
  2. install a plugin (that we could potentially develop) that
    • bundles the compiler, merlin, dune(?), ocamlformat, and a fixed number of selected packages which Just Work
      • we can achieve this platform agnostically with the help of Js_of_ocaml
      • we could also ship platform specific executables for better performance

Surely for most “realworld” development in OCaml, this setup won’t be enough as opam support (not so sure about dune) would be quite non-trivial this way, but for someone who’s eager to tryout the language and write some serious code, this can be a good first step. It may also be very helpful for students who’re taking a class that uses OCaml.

1 Like