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?

7

I regret going into detail with that article. Can we please split this topic into three:

  1. Should tutorials and other content on ocaml.org be AI-generated?
  2. A discussion about the quality of the tutorials on ocaml.org. The quality has been lacking for longer than AI has been in use, and so can’t be attributed solely to slop.
  3. Who was the most confusing and verbose defaults? Dune or opam? As a counterpoint I can tell it was a headache to globally have OPAMWITHDOC=true/OPAMBUILDDOC=true and/or OPAMWITHTEST=true. I’m not really interested in this discussion, though.

My intention was to bring up the first topic, and I think the second topic is related. But please let’s focus on the first topic in this thread.

I’m worried what message we send newcomers to OCaml when they in the ocaml.org tutorials are greeted with a disclaimer that they are written with AI assistance.

8

What kind of message do you think this sends to newcomers? Is it because of the perceived low-quality of the outcome?

9

We don’t care about you.

10

I think newcomers’ perception oan go either way, really. There are lots of people who are drawn to stuff that is AI-friendly, and lots of people who are drawn to stuff that is not AI-friendly. Deciding in favour of any approach will make OCaml more appealing to some and less appealing to others, but we can’t avoid making a choice.

The reason I love Haskell’s motto (to avoid “success at all costs”) is because it’s a reminder for us to not let go of the things that make our community/ecosystem so valuable in the first place, while we are pursuing “success” or “growth” or some other outcome. It would make me sad to see “appealing to newcomers” being a reason for making a decision that is controversial within the existing community.

11

I think the message is also: “We don’t care about our own project.” OCaml.org is ostensibly the most authoritative source of OCaml information. If its pages have disclaimers like this, then that makes the whole OCaml project look sloppy and unserious.

Ignoring the AI angle for a moment, since that has its own baggage, I believe the fact that there’s a disclaimer at all is automatically a bad sign. Imagine if the first line of the About page was, “this page was copied from Wikipedia.” If I saw that as a newcomer, I wouldn’t bother to waste my time on the rest of the site. (As it happens, the actual ocaml.org/about is adapted from another source, but that source is high quality and has a proper citation, not a disclaimer.)

If the page’s content is questionable enough that it warrants a disclaimer, then maybe it’s worth reconsidering if it even belongs on the site.

12

I think it’s the same argument we’ve always had in this forum: if the text is copy-pasted from an LLM, then why are we coming here to read it? We can just prompt an LLM and get pretty much the same thing ourselves. We want our resources to be authoritative and have the benefit of real human effort put into them. Error-checking, brevity and concision, recommendations of best practices from real people. That’s how we set ourselves apart.

13

Most of the lines @reynir quoted aren’t AI-written (see the commit and blame for lines 24–43 and line 204). Questioning quality is always acceptable, and so is questioning the use of AI. I’d also question the choice of human-written passages as an example of AI writing.

We all want quality material on ocaml.org. We reviewed the AI-assisted texts and concluded that the balance of quality and informativeness justified publication, given that they covered either tools with no documentation or texts in need of improvement. We added the disclaimer for transparency about their origin. It seems to have defeated its purpose, as it is perceived as giving up on quality.

So that we can discuss how to handle AI-assisted text on ocaml.org without it feeling like a fait accompli, I’ve opened #3834, which removes served AI-written pages and reverts the two opam tutorials to their human-written versions (human changes made on the AI text are preserved). I’m waiting for your feedback before merging.

Is this a fair enough outcome?

14

What @reynir highlights concerns two essential issues:

  • the first is that the use of AI by the maintainers of ocaml.org (who represent a diverse community) has never even been brought to the community’s attention (which could have opened up a legitimate debate). Fundamentally, there is an implicit acceptance and trust that certain individuals and companies maintain ocaml.org. Beyond the work required to maintain the site’s content and infrastructure, it is also a matter of maintaining that trust and, in my view, this discovery has somewhat eroded that trust. I recognise the effort you have made in terms of transparency, but I also hope that this transparency in content generation and infrastructure maintenance is considered the minimum expected by the community.
  • the second question can be summarised as follows: should we use artificial intelligence to generate educational content? My opinion is quite radical (since I apply it to myself as well): the answer is no. I am familiar with and have experienced the problem of having to proofread AI-generated content for code, and I am certain that anyone in the same situation would insist that the person proposing the content carry out a minimum amount of editing and adaptation to make the review process easier.

Thank goodness, interactions on pull requests allow us to provide feedback on the content and ask the person who submitted the AI-generated content to make more of an effort. No such structure exists when it comes to (top-down) educational content. As far as I’m concerned (and I think @dbuenzli puts it more succinctly), using AI for educational content means neglecting the very essence of what makes for good educational content: the transmission of knowledge. This fundamentally corresponds (normally) to human interaction, and nothing else.

15

I agree with some of the points made by Romain, but I don’t understand the “using AI for education content means neglecting the very essence …”. I’m in the opposite camp, I think AI is fantastic for educational content. I started to use it for my https://principia-softwarica.org/ project to make books to teach humans about the whole system. It accelerated a lot my work and produces IMHO great content. It still requires lots of work from my part, because I proofread, refine the prompt, ask to generate again the explanations, and because the AI can understand quickly things a human don’t, but boy this thing helps … What I expected would have taken me 3 or more years takes me now a few months (I’ve spent already 5-6 years on principia, unpaid, so anything that can help me I take).

I think what we have is many people have a visceral reaction against AI. I can understand, a recent talk by DHH at rails world goes in depth about it. But it’s not the case for everybody, so I’m not sure we want to split the OCaml community based on this criteria. In the mean time I think we should avoid using terms like “Slop” (I can tell you I’ve seen far more humans slop code than AI in my career) and complaining about something just because it’s made by AI. Either the content is good, or bad; how it was produced is less relevant IMHO.

16

I think it’s fine to have a slop discussion.

Writing for OCaml.org has always been difficult in terms of how do we present and frame things for people who are entirely new to OCaml (or entirely new to programming). A part of this is because the tooling has some specific ways you need to use it in order to not set up footguns for yourself. Choices were made with the intent to help people avoid running into very avoidable issues around using the wrong opam switch (because of opam’s model of having both local switches and global switches and it not being obvious to a beginner which one opam will use - arguably, no one should even have to learn this when they use the tools on default settings out of the box and that’s why efforts around Dune and making it do package management exist).

Can we treat “slop” and “AI” as two axes? Like this:

human AI
not slop awesome fine
slop let’s improve the content let’s improve the content

Traditionally, people have been cautious to call out things that can be improved for fear of hurting the author’s feelings. However, this does a disservice to all of us. So thank you to everyone who brings up specific and actionable improvements on the content! In fact we’re happy to take PRs (with or without AI) that make improvements to the tutorials, just as we’re happy to take reports on what’s bad and ideas to fix it.

I feel like using AI makes producing written content (of varying quality, depending on prompts, amount of human input, and requested writing style) so much less personal that it should feel easier to criticize the content as such without fear of hurting a human author’s feelings. Realistically, the bottleneck has always been review from different points of view.

Regarding AI disclaimer labels, I think that they are not helpful for content that has been reviewed and edited by people.

On whether OCaml.org should even have any tutorial type content: OCaml.org is basically the “landing page” of OCaml, so it should point people to places where they can learn everything they need to know to use OCaml. Whether tutorials and extensive documentation on OCaml.org should exist now that people can use AI to peruse and restructure the tool maintainers’ documentation is another question.

From a SEO perspective, and also from a perspective of a newcomer exploring the site and looking to understand what’s the “blessed” ways to do things in OCaml, having such content on OCaml.org is useful. Especially if it links out to the other domains where good materials are found. What’s perfectly clear is that the content must be actually useful to the reader and it must be correct.

17

I think this misses a crucial part of why I personally don’t like reviewing AI output: when you’re interfacing with a human creator, you have the opportunity not just to improve the outcome but to upskill the creator. You are correct that it requires a bit more tact, but writing advice or code critique will (hopefully anyway) improve the future output of that person, and builds a working relationship with them.

By contrast, there’s really no such hope for such a thing with the current generation of generative AI tools. You can maybe put it in an AGENTS file or just hope it’s still in context from the last time, but they’ll never learn your style really, and arguing with a mechanical brick wall gets tiring.

18

In my experience, AI has been far more receptive to feedback than humans :slight_smile: I’ve seen far more humans learning nothing from critique. And AI do learn your style, they are actually fantastic at that.
But this degenerates in a new kind of flamewar … Let’s improve content! I think that’s the important conclusion.

19

Be mindful that many people’s reaction against AI is absolutely not visceral but entirely rational and this starting from more than a single different set of premisses, each of which is interesting to consider on its own.

20

GOAL: Good documentation.

How the sausauge is made? Don’t ask.

Regards

David