What are the biggest reasons newcomers give up on OCaml?

I’m not sure anything actionable will come of this thread but I’ll give my two cents :slight_smile:

For me the main thing which I find lacking and could be improved is documentation.

Ocaml is different enough that it’s quite easy to get lost at the beginning. If you want to dedicate, let’s say a morning, to explore the language knowing nothing about it, you’ll probably fail. Which is not the case for other languages.

I’ll give an example of a bad documentation experience:

You want to find out how dealing with SQL would be in Ocaml, you find about caqti.

You go to its repo, the example doesn’t actually contain any CRUD operations :frowning:

You look for examples, see that the README points to an article/tutorial on Medium, which talks about jbuilder which then leads you into a rabbit hole, so you waste time trying to understand what this tool was and how it is related to your current problem of trying to make your demo work.

I’m interested in Ocaml enough to push through but I can easily imagine some people dropping out at this stage, which is unfortunate.

I’m not picking on caqti btw, it’s just a random example. I’ve also stumbled upon certain projects with absolutely no documentation - such a shame.

Of course, we can go read the source code, etc. But my main point is more documentation = less friction = better :slight_smile:

IMO, the Ocaml community should take inspiration from Elixir, for which its tool-chain enables generating documentation such as this:

I’m not quite sure what the documentation story of Ocaml is, and I understand the tooling keeps on improving.

Overall, I’m very happy with Ocaml, but if documentation (and maybe the related tooling) could be improved it’d be that much better!

9 Likes