Is ocaml.org slop now?

Ecosystem
1

Excuse the inflammatory title. I saw today this tutorial, and it has a disclaimer at the top that it was written with AI assistance and reviewed by the OCaml.org team:

Managing Dependencies With opam · OCaml Documentation (permalink to the source at the time of writing)

I’m a bit sad to see this. Partly because I detest AI writing, but also because the quality of the tutorial is in my opinion quite poor. First of all, opam.ocaml.org has decent documentation already: opam - Documentation index I can understand there could be a need for a tutorial-style introduction to using opam, but I think the tutorial should link very early to the fine opam documentation. Instead, at the end we find a link to the “opam documentation for more details on the opam syntax” which links to a random section in the middle of the opam manual on package variables(?!)

Let’s analyze the first page or so of the tutorial. It starts early suggesting you run

opam install . --deps-only --with-test --with-doc --with-dev-setup

This is not bad advice, but there is no explanation or motivation for the army of flags in this invocation. Next, we have:

If you prefer to install your dependencies in a global switch instead, select it first:

opam switch set <switch_name>
eval $(opam env)
opam install . --deps-only --with-test --with-doc --with-dev-setup

First of all, this doesn’t actually work if you have a local switch as suggested you do in the beginning of this tutorial. The local switch will be used.

Once the dependencies have been installed successfully, and assuming the project uses Dune as the build system, you can compile it with:

opam exec -- dune build

Or if you set your environment with eval $(opam env):

dune build

Now we have some confusion here. We were just told to run eval $(opam env) and then we do opam exec -- ... anyway?! And then we get explained if we do the thing we were just told to do we can write it differently. And no mention of the shell hooks the reader hopefully installed makes all this unnecessary.

I will end my rant here, and I hope we can have a constructive discussion on what quality we can expect of the tutorials on ocaml.org. I know there are people on the OCaml community with excellent technical writing skills. Maybe ocaml.org shouldn’t try to write tutorials for everything, and maybe more collect links to existing documentation.

2

FWIW, there’s a very good (hand-written!) manual by @rjbou about opam on the OCamlPro blog Opam 101: The First Steps | OCamlPro – maybe ocaml.org could integrate such a good piece of documentation instead of vibe writing everything?

Not sure whether OCaml.org · OCaml Governance is still up to date, but it would be great to hear from them what their thoughts are about ocaml.org (and I completely agree that adding slop there should be a broader discussion with the OCaml community). @avsm @sabine @cuihtlauac @professor.rose @tmattio – are there regular meetings of the ocamlorg team? have there been slop discussions?

3

I added the disclaimer recently because that tutorial indeed contains AI-generated text.

This tutorial was created in September 2021. Roughly 12% to 15% of the text is AI-generated; the attempt was to make it more step-by-step. We’ll happily merge all proposed improvements to any tutorial, as well as new tutorials, guides or other contributions.

4

I don’t think this post is necessarily about the content of each articles individually, but rather: should the community(?) website contain material generated by LLMs? It very clearly does today but i think it should’ve been discussed prior with the wider community.

5

I agree something akin to the compiler’s AI.md should be added to ocaml.org. Let’s draft that in a PR? Also, as before, contributions that remove low-quality text (in whole or in part) are valid.

6

I think this isn’t anything to do with AI generation as it is that our defaults are indeed rather confusing and verbose.

Like the above! It does make one wonder if --with-test, --with-doc and --with-dev-setup should be the defaults these days for a source based package manager, with options to do --without-test and so on for the rarer cases where you just want the main package.

Is anything more confusing (to a human or AI) than opam installing something to get the dependencies and then having a dune build fail straight afterwards when we try a build?