one common complaint/suggestion I kept hearing from different people is that it should be simpler to install OCaml.
People arriving on ocaml.org reported getting confused by the comprehensive instructions on the different methods to install OCaml in the “Get Up and Running With OCaml” tutorial. Tbh, I myself was confused reading all of that. I am a relatively new OCaml user (using OCaml since September 2022, so bear with me and assume ignorance when I do something stupid - I am happy to be educated ).
I have a proposal on staging.ocaml.org on how to reduce friction when “onboarding someone into installing OCaml”. It replaces the “Get Started” link with an “Install” link that leads to a dedicated TL;DR “Install” page. To make it truly simple, I had to be opinionated and pick one installation method over the others. I went with installing opam via the shell script, and then showing people how to set up a global opam switch with OCaml 5.0.0 as that seemed the quickest/simplest way to get the most recent versions.
I think what is missing on the proposed “Install” page is probably a call to action where to proceed if you need a tutorial for the next steps.
I believe that, when a new potential user manages to install OCaml quickly, it gives them the reassurance into the tools that they are more likely to go ahead and try a tutorial.
Please review, rip apart, make change suggestions - I do not want to rush ahead with this when I am not entirely sure that these are the (quick!) instructions we should be giving newcomers.
(Ok, but now I’m back to tidying up the package pages, as it was actually planned - there’s still a lot more to do. )
On the unix installs, in the first step I would add a hyperlink on a page that explains how to use your system packager or other methods. Some people are rightly averse to these bash/curl instructions. Something like (possibly in smaller, after the bash thing): Or use your [system package manager.](/opam-system-install)
In both unix and window cases you want to add a final step as link on another page where to continue to do something ! Maybe not something as long as Get Up and Running With OCaml · OCaml Tutorials, but something simple to compile a hello world program. Could be as simple as
I’m still reticent running bash commands from the internet like is suggested. To make things a bit better, it might be good to have a convenient way to check the script (without having to manage to select the URL from the overflowing text box to copy-paste). I’d suggest having two buttons on the side of the text box: one to copy the line, and one to jump to the script.
bash is not the most portable of shells and the script itself uses the #!/bin/sh shebang. So maybe swapping for sh would be better.
Some people are rightly averse to these bash/curl instructions.
I am.
Trouble is opam deb file recommends ocaml, and both Ubuntu & Debian install recommended dependencies by default. That behaviour has to be unset if one wishes to install opam without ocaml in those distros.
Yes, but anybody’s who fluent with their package manager and doesn’t want to install optional dependencies can do so. (And installing those dependencies doesn’t cause any problems, anyhow.) The proposed page is aimed at newbies who just want to get up and running with as little hassle as possible, and it does this very well.
So what I might recommend–instead of explicitly describing how to use one’s package manager–is to preface the page with something along the lines of “There are many ways to install OCaml, including via your distribution’s package manager. These are described at “Get Up and Running with OCaml.” The easiest way to ensure that you are running the latest version of the software is to follow the below instructions.”
In addition to @dbuenzli’s suggestion of including a minimal “hello world” project, I think it would be helpful to point people to Dune, Merlin, etc. So a postscript of, "OCaml offers a number of tools to ease the development experience, including the Dune build system and plugins for your preferred editor. These are discussed at “Setting Up Development Tools”.
I started learning OCaml only recently, and I too was overwhelmed by long installation instructions.
Getting straight to the point is what you need in the installation instructions.
My view is that instructions should be as beginner-friendly as possible and cover the most popular use case by default. The most popular use case when installing the toolchain for a new programming language for the first time is to compile and run Hello, world! as quickly as possible. And the shorter the instructions, the quicker people can get started with the language. And more people will actually get started.
I like the simple bash commands as they are used in Nix and Rust which seem to be doing well. Some comments:
I think MacOS needs to be written as macOS; at least that is what the apple website claims.
I don’t think we are consistent with how we capitalise opam. It could be opam, OPAM or Opam. When it is all lowercase, having it in monospace clarifies that we are talking about the command more than the “concept”. Whatever is the correct choice, this page should be the “official one”.
Maybe the link detailing alternative installation methods should have a small header: “Want to use your own package manager?”. Something short and snappy preferably. I might be blind, but I completely didn’t see the link at first.
Pictures/emojis of penguins, apples and windows might help young people like me with short attention spans.
Thanks, that’s a great list of points that do help this become a great page!
I’m glad I didn’t spend too much time polishing that and instead went for early feedback. It’s really great to see how it all comes together with multiple people looking at the problem from different angles.
v2 of the tentative install page is now published to staging.ocaml.org. It got a tiny bit more comprehensive, while still being as brief as I could make it.
I couldn’t resist touching up the “Getting Up and Running” tutorial a bit to give it a proper, hierarchical section structure and better section headings, and remove noise. Hopefully things are a bit less confusing now. If you see more opportunities to clarify, let me know! (One thing I didn’t touch at all is the “OCaml on Windows” tutorial, for example.)
ETA: I’m aware that, in the Unix-derivatives instructions, I would need to add a step to run opam init, unless opam’s install.sh script can be extended to include it (either as in Run opam init for a fresh install by sabine · Pull Request #5501 · ocaml/opam · GitHub, or with a prompt Run opam init now [Y/n]). Running via sh instead of bash also requires a slight change to opam’s install script.
One thing I really liked about the previous draft was minimalism. The two-column layout and sparse text gave a simple, no-scrolling-required snapshot of how to install / set up OCaml. Long-form documentation has its place, but I think the hot-path of getting new users to run “Hello World” should be as simple as possible. A few concrete design suggestions:
I would move the OCaml platform tools install back into a second column
Move the “if these instructions do not work for you” text to the bottom of the page, below the “First Steps” button. Also, I would reduce the padding at the top of the page. IMO, the actual instructions start too far down on the screen.
On a similar note, maybe on large screens the OS selection buttons could be at the same level as the “Install OCaml” header, but aligned to the right side of the page?
“Instructions for …” should be “Installing OCaml on …”, to contrast with the other column. Maybe numbers should be added too, reinforcing the order of the columns.
Could the “view this shell script on GitHub” text/icon be an inline button next to the clipboard to save vertical space?
Instead of “What if I don’t like shell scripts”, I think the dropdown should be “Installing Via Package Manager”. Instead of linking to the “get up and running” page, we could just directly embed code blocks. Why not move as much as possible towards making the old page obsolete?
I would add a one-sentence blurb (with link)! that opam manages both OCaml compiler versions and packages. People with little programming experience might be confused why the thing they are installing is not called “ocaml”
With these changes, I wonder if there would be enough space in the second column to add a dropdown about the utop REPL and a tabbed dropdown about editor config to the “install” page. Then, the “next steps” would be starting a project. This suggests the possibility of adding another simplified page (or a section below on this one) about dune and running “hello world”, as well as ocamlformat and odoc.
Considering the longtime complains about OCaml’s documentation and complexity, I think that onboarding users through toolchain and dev tools setup in only 2 screens would be a big win.
V3 is up at staging.ocaml.org, incorporating most of these suggestions. Thanks so much!
I don’t want to go overboard now with reworking the “onboarding to OCaml”, as there’s a lot of other construction sites that need some love.
However… I agree that there’s sooo much potential in writing better tutorials and improving the existing ones, coming from the viewpoint of “how can we make onboarding more fun, more frictionless, and more successful for new users”. We must take into account that there’s different kinds of new users:
people without programming experience
people with experience in predominantly non-“functional programming” languages
people with experience in functional programming languages
people who know many languages and paradigms
I assume that, the more a new user already knows, the more likely they are to skim-read.
There’s a lot of opportunity for contribution here.
It’s looking good on the third iteration. Some misc feedback:
The platform buttons for linux and mac are the same page, so perhaps the buttons could be merged.
macOS should come before BSD since it is more common. i.e. “Linux, macOS, or BSD”.
There is quite a lot of wasted vertical space above the platform buttons and on their right. I don’t know if moving the platform buttons to the side might make this better. One of the consequences of the spacing is that the Windows page doesn’t fit on my 2256x1504 screen (so the problem is probably worse on a 1920x1080).
“as well as packages.” → “as well as any additional packages.”.
For opam switch, you could hyperlink to explanation of switches in the OPAM manual. In case anybody is curious.
In “Other installation methods”, instead of using “Or,” I would use “Alternatively,”.
“Congratulations, you have installed OCaml!” → “Congratulations, you have now installed OCaml!”
The text for opam switches differs between linux and windows. Instead of explaining opam here I would explain opam in the diskuv step above. Saying diskuv installs ocaml opam and dune on windows etc. (probably don’t need to go into too much detail however).
Users on windows might wonder why setting up development needs an extra opam command unpinning packages on Windows. A small drop down/hover text explaining the need for it might be useful.
The output of opam switch list-available is basically unusable for a newcomer. I suggest to use instead opam switch list-available ocaml-base-compiler (and if there was a way to not display beta versions, it would be even better).
Sounds like I need to get all of the Windows pages updated. And I’ll need to make a regression test on the exact commands that are used on those pages. Thanks; I’ll update you privately when I finish that.
I blanked out earlier on what you were trying to do. When you run the Windows installer the development tools are installed in the user’s PATH. Yes, you can also create a switch, but I find that unnecessary complexity for an OCaml beginner. (I liken it to asking a new Python user to learn about Python virtual environments before they learn about Python itself). For example, I’ve taught using the Cornell 3110 OCaml course by just using the Windows installer; no extra switch necessary. And I’ve have an open issue to do the same with Real World OCaml (Real World OCaml recommendation · Issue #28 · diskuv/dkml-installer-ocaml · GitHub).
utop is just an example. Specifically the following work “out of the box” without an extra switch:
dune
ocamlformat
VS Code + ocaml-lsp-server
The other tools:
odoc is also installed out of the box but untested since I rarely use it directly (and only as part of a switch)
merlin is not installed. And since I never use ocamlmerlin, and I doubt 99% of Windows users will use it, I’ll probably never install it as part of the beginner global binaries
So, I think we can get rid of the final 3 of 4 steps that are on your new Windows tab. The Windows DkML newcomer experience should be easier than the existing Unix experience. Maybe this needs a sync-up! DM me if needed.
My assumption is that three kinds of people primarily benefit from the install page:
people who are completely new to OCaml and want to program in it
people who only want to install OCaml to build or run some existing tool written in OCaml
people who have used OCaml, but then forgot how to install (or they went away for a while and are now coming back, looking for the way to set up OCaml again to work on their old projects)
ETA: the version that is now on staging should be pretty reasonable. While there’s certainly more little details that could be improved, I condensed this to the point that I feel it’s possibly ready. I checked that the install instructions work on a fresh Ubuntu docker image.
Overall, I tend to think there is too much text, with installation instructions not so easy to spot (e.g. the paragraph about updating one’s shell configuration file). (About this very topic, having non-interactive commands seems better IMO.)
It seems to me the PPA version of opam lags a bit behind the latest stable release. I haven’t checked recently but on Unix, I’m not sure it downloads OCaml 5.0.0 when you do opam init, does it?
I would advocate for not talking, or very little, about switches on this page. I think the notion of a development sandbox is a matter for everyday developers, not beginners, so working in the global switch seems enough. One way to talk about switches (and other stuff such as dune and opam configuration files) could be to add a second web page for users that aren’t beginners anymore and need to do some “professional-grade” development.
Setting up development tools would really feel nicer if you could just opam install a single package pointing to dune, merlin, ocaml-lsp-server… In principle, this package would be user-setup.
As long as the ocaml platform is experimental and does not work as the instructions above (“The tools are not installed exactly the same way as with opam install […]”)., I think it should be removed from this page aimed at beginners.
It’s too bad dune init doesn’t create an .ocamlformat file…
Finally, I know Rust isn’t the panacea and we don’t have to mimic everything they do, but their Getting Started page is really short in terms of text and commands to run, so I think it could work as an inspiration.
).
)
