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

Community
,
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