Why the OCaml ecosystem is poorly documented?

[mars0i]

@cemerick

Just as a bit of a point of order: your Clojure link is not to the actual API reference, but to clojuredocs.org, a community-maintained repository of additional documentation layered on top of the official documentation. (I mention this only because I had some hand in helping clojuredocs get started many years ago, where it was a community reaction to the core dev team explicitly not wanting to have the sort of expanded sets of examples and cross-referencing that you and others are looking for in OCaml.)

Some details that might relevant to some of the subsequent discussion. (I made related points in a earlier discussion several years ago.)

• When you enter (doc <function-name>) in a Clojure REPL, you get a (usually) short docstring that lists the arguments with a brief description of what the function does. There are (typically) no examples. If you’ve configured your editor, you can get the same thing in the editor.
• With some editor configurations (e.g. vim-iced for vim/neovim), there is a separate command to pop up the ClojureDocs page for the function the cursor is on. This will include the official docstring, plus user-contributed examples and user-contributed cross-references to related functions.
• I personally don’t like overly long docstrings. When you just want to be reminded of the syntax and what the function does, examples are annoying.
• But I love ClojureDocs. Because of the examples, it’s indispensible. I can view it on the web, nicely formatted, or if I want to be able to pop up ClojureDocs pages in my editor, I can configure my editor to do that as an operation distinct from displaying the docstring alone. This is the best of both worlds.

That seems like one possible model for separate brief documentation and examples: example-free basic function documentation, with a separate, easily viewable example repository that can be viewed on the web or pulled up in an editor.

@cemerick

I do see the value in having such examples; having them available for OCaml libraries would I’m sure be helpful. The big questions are, who’s going to write and maintain those examples, and what does the infrastructure look like for maintaining them (i.e. having them in a testable form so their validity can be checked and expected output can be produced automatically).

When I mentioned ClojureDocs as a useful model in 2017, there was concern that user-contributed examples would require work to curate them. I asked around about how ClojureDocs examples are curated, because I couldn’t find any information about who was in charge. The answer is that ClojureDocs examples are not curated—at least not centrally or systematically. Anyone who creates an account on ClojureDocs can add an example and can edit others’ examples.

Yet I have never seen a horrible example on ClojureDocs. Sometimes there are examples that pretty much illustrate the same point as other examples, but that’s not necessarily bad. I have to assume there have been bad examples added to ClojureDocs at some point. I imagine that someone came along and noticed and improved or removed those examples. I don’t know. ClojureDocs works, and it’s great.

I think that if Clojure were as popular as Java or Python, ClojureDocs would be a mess, because more users means there’s a greater chance that someone will exercise poor judgement.

But Clojure is not that popular, and it’s largely a language that’s chosen rather than just a language that people use because they know it’s popular. There are fewer people to create random noise, and maybe people who use Clojure tend to be people who respect the language and the community. But that sounds like OCaml.

So maybe all that’s needed is a system that generates editable webpages headed by the official documentation, with a system for allowing users to add examples. This could start with the standard library, but maybe maintainers of other libraries would want to follow the same model. Then just wait to see what happens. If a lot of junk starts appearing, one can worry about how to deal with that then. I think that’s unlikely.

If “OcamlDocs” takes off, people might start adding functions to editor-IDE configurations that allow displaying the examples page for each function. Or maybe people would be happy viewing the examples only on the web. I sometimes work with a browser pointed at ClojureDocs so that it’s always available.

(Maybe one difference is that OCaml is a teaching language for CS at some universities. I’m not aware of Clojure being used in this way. If there’s a fear that students would add noise, maybe more policing would be needed?)