I think that the usability of the OCaml ecosystem is very important.
I feel it is one of the highest-priority tasks for the OCaml community to thrive, possibly the most important today. We should discuss openly what can be done to improve the current state, and encourage people to contribute to this improvement by highlighting moderate-cost tasks that really do help.
There are two partly-orthogonal ways to improve the usability of the
OCaml ecosystem for beginners. One is to document it better: give more
information about each tool, give some opinionated guidance on tool
selection to reduce decision fatigue, update various parts of the online
information to make a more coherent whole where each part is informed
of the rest. The other is to improve it by improving existing projects
(evolution) or starting new ones (revolution). It is unclear to me what
are the respective usefulness, on the long term, of those various
options, and what we should encourage would-be contributors to do. It is
clear than there is not only one Right Thing to recommend, we need a
bit of all of that at the same time, and different approaches may suit
better different parts of the problem.
When I started being active in the OCaml community a few years ago (let's say around 2008), the "pain map" was fairly different from what it is today. We have improved considerably on many fronts, but I am afraid that we may have largely prioritized improvements that would benefit the existing userbase of OCaml semi-experts, at the detriment of those designed to lower the barrier of entry. Below is a rather rambly and subjective list of the various aspects I can think of, and how they evolved over this time period.
+ At the time, the development of the compiler distribution felt was perceived as a closed, opaque process. There is always room for improvement, but I think it is fair to say that today it is evidently not the case anymore. The compiler distribution, as a software project, welcomes external contributions, and has a fairly active network of external contributors. We are lucky to have such a enthusiastic crowd hacking the compiler, and I am sometimes surprised that other important and useful tools in the OCaml ecosystem are not similarly gifted with external contributions.
+ Another major hurdle for OCaml users was the lack of a consensus solution for packaging. Debian and RedHat/Fedora were (and still are, thanks to excellent maintenance work from their OCaml package maintainers) two safe islands were development environment were easy to setup, and GODI had a loyal and satisfied user base, but a large part of the community still considered external dependencies as grave sins that impeded their use of OCaml software. ocamlfind and OPAM have brought an end to this middle-age of OCaml library usage, and we now consider it a given that other people than ourselves will be able to use the libraries we distribute (without having to import their sources in the source tree). (History always moves a little bit slower for our brave Windows OCamlers, but some unsung heroes are doing their best there as well).
- One thing (the only thing? for non-Windows users at least) that is currently rather bad about OPAM is its documentation. This is partly due to the fact that it is a very flexible tool, and partly to the fact that writing good documentation is Really Hard. This is one area where I think everyone could contribute small improvements that would have a large collective impact.
~ The third major blocker that I remember being clearly identified at the time was the lack of a "extended standard library" that would cover the everyday needs of OCaml programmers. Batteries and Core (the latter internally inside Jane Street at first) were started around the same time as attempts to fulfill this need, and Containers would be a notable more recent entrant. This is a mixed success at best: we now have good "extended libraries" which make many user's lives better, but no real "standard". It is unclear we should keep trying to feel this role, however, given the current use of distributing smaller, one-purpose libraries; I don't think that the OCaml community at large currently identifies this as a blocker high on the TODO list. On the other hand, the situation is arguably unclear and it may be the case that beginners find this confusing.
+ Interfacing with C APIs should be easier than it previously was thanks to the ocaml-ctypes project.
~ The library ecosystem is still poorer than we would like, with some functional areas that are not well-covered. This can be explained by the modest size of the community, and is improving at a steady pace.
- There is no effective standard for running the internal tests of OCaml packages, which would be useful for quality analysis (and in particular be of help when assessing the impact of changes to the OCaml compiler or other parts of the base ecosystem).
-- There is no effective standard for releasing and finding the documentation of OCaml packages. The convention of documentation comments in .mli files (protected both by the existence of the ocamldoc tool and the insistence on have separate interface descriptions) means that there often *is* decent documentation for OCaml libraries, but it can still be hard for users to find. As Hendrik Boom reports above, this disproportionately affects beginners.
+ The Merlin project now provides solid IDE-like support for a large portion of the OCaml community; in many ways it goes above and beyond the state-of-the-art in terms of language-specific support for partial program buffers. On the tooling front, ocp-indent also seems to be a success in terms of satisfyingly solving its problem area and getting widely adopted, but other tools (otags, ocp-index, ocamloscpe, {ocp-,ocaml}browser) seem to have more insular usage patterns. Finally, we cannot deny that the best OCaml programming experience is currently offered by editors from the 80s (Emacs and Vim; notable exceptions are half-decent support for Sublime text, and the laudable OcaIDE effort for OCaml on Eclipse that enables teaching OCaml in some universities); this is another aspect in which newcomers and beginners may be under-served by the current efforts targeted at the more vocal parts of the user community.
~ Another piece of the OCaml ecosystem that expert users like to complain about is build systems. There are many of them are none are entirely satisfying -- exactly the right environment to get rants from expert users. In practice, I feel they are all rather satisfying, and I wouldn't be ashamed to see a beginner pick any of them for their project. Decision fatigue may be part of the complaints from beginners on the ecosystem, however.
~ Relatedly, OASIS has only a mixed standing among expert users. In practice it has a large userbase and seem to work rather well for them. It is currently unique in the space of "project description" systems, but it currently does not go far enough in this direction -- in particular the Merlin files have to be written independently, which feels like a duplication of effort imposed on the users. I'm always a bit surprised that Sylvain Le Gall does not receive more external contributions on this project. This might be due to some of the technical aspects (auto-generated files) being perceived as unwieldy.
+ We have a nice website (
http://ocaml.org/ ) that was built from the start as a collaborative, community-driven process. (the
ocaml.org organization is not just the website and manages some very useful infrastructure). Some parts are in need of improvement (a personal cringe of mine is the way the spotty "tutorials" section overlaps with the language manual and standard library documentation), but there is a clear and easy process to improve. Do interview OCaml beginners around you about which information they had a hard time finding, and submit pull requests to improve it!
(On a maybe sourer note, back in 2008 we had the COCAN wiki as a very useful community-maintained OCaml resource (not the same as the "brion wiki" that never made it easy for external users to contribute), and it has since fallen out of favor. Distributed good will is not quite enough to produce high-quality online documents, and community-edited places are harder to keep relevant than we may think.)
+ As François Berenger notes above, we do have a fairly efficient beginner-support network in place through the caml-list and ocaml_beginners mailing lists, the #ocaml IRC channel and the StackOverflow community. It is a bit hard to keep track of all the cool new places (most being proprietary walled garden because startup money trumps benevolent sunday-afternoon contributions) people expect to get help from, but those that I know about are well served.