Exploring this website I found some interesting threads about the problem of attracting new programmers to Ocaml; while these threads often end up raising the temperature, they’re not uninteresting, and one has to face the reality. One of the suggestions was to modernize the documentation. I totally agree.
First of all, finally moving from the 1990-styled inria web site to the newer ocaml.org was a great decision. One can dislike the design of it, but at least it doesn’t look so outdated, and this is very important.
But there is still the problem of the documentation. To my opinion, the https://ocaml.org/docs/ page should be improved, as it does not advertise enough the existing doc, and is probably disappointing for newcomers. Here are some suggestions.
The front page https://ocaml.org says “Documentation
Install OCaml, look up package docs, access the Manual, get the cheat sheets and more.”. This is appealing. But once you are on the Doc page, the info is quite scattered; it’s not so clear how to access these. My suggestion is to have a large menu covering the most important aspects.
To my opinion, the “Ocaml Manual” is by far the most important piece of information, at least for me, this is the one I’m visiting the most often. But it’s not even part of ocaml.org. Why not make it an essential part of ocaml.org? Of course, this includes modernizing the css, maybe using
odoc, or using this very nice contribution: https://www.streamingspring.com/ocaml/docs/, see Modern Standard Library Documentation, but also more:
The ocam Manual contains too much information packed into a single “component”. It is too bad that such a nice document, with chapters that I often realized I forgot, or new chapters I didn’t notice, is not better advertised. My suggestion is to have the whole https://ocaml.org/docs/ page in dedicated to it, but also to split its contents into separated, more accessibles components (it’s easy, they are just the various parts of the manual):
- An introduction to OCaml (which could also be called “the Ocaml Tutorial”, in reference to the Python Tutorial https://docs.python.org/3/tutorial/index.html)
- The OCaml language (or “Language reference”)
- The OCaml tools
- The OCaml library (this could be called “The API”, like
These are the four blocks that should appear prominently on the doc page, instead of the current blocs with links, videos, books advertisements, etc.
A final word; there will be maybe positive or negative reactions to this post; or maybe none. But from what I have read it seems that most of the community agrees on the importance of improving the documentation somehow. So, let’s not waste too much time in discussions; in this post I’m only concerned about appearance, and not content, so it should not be too delicate to handle. I’d be happy if someone took the decision to do something quickly, be it or not along the lines of my suggestions above, be it or not approved by the “majority”. If we wait another 5 years, then we will be 5 years late in terms of trends and design, etc. At this point I’m totally ignorant about how to concretely help modifying the website, but I’m happy to give a bit of my time to help.