This thread launched a number of discussions about improving the OCaml documentation. Unfortunately as that thread was very long and had a lot of other topics being discussed, the documentation discussion got buried. So, this is an open thread to discuss ways to improve the OCaml documentation.

[image] Chris00: Do you know that you can edit the page in Github itself and then push the PR from there? I did know. But it works by forking the repo into your github account and doesn’t keep it synced to the original repo, and if you want to test your change it doesn’t help you by showing t…

There’s been little or no change in the content, but I would argue the Sphinx version, merely by being better formatted, is vastly easier to read. Personally, I find the new coq documentation much harder to navigate. The tactic index – which is the main entry point for the documentation day-to-da…

I should point out that I think Sphinx produces nice read-able output for tutorial-style documentation – where there are large bodies of text with the occasional note or code sample. However, for API documentation it tends to degrade into a cluttered mess that is hard to read. This is true of a lot …

[image] lpw25: Personally, I find the new coq documentation much harder to navigate. The tactic index – which is the main entry point for the documentation day-to-day – is hidden at the bottom of the side-bar. The tactic index itself is also less pleasant to use. Those are both fixable. […

Those are both fixable. Everything’s fixable. The point is that the most important thing about the documentation is how it is to work with day-to-day, and that sometimes people are willing to sacrifice that in order to get something shinier – which is a shame. The coq manual shouldn’t have been s…

[image] Yaron_Minsky: take a look at Racket’s docs These are laid out really nicely. Easily the most readable online documentation I have seen. What do they use? Is there a stylesheet that OCaml could steal? (sphinx or otherwise?)

I agree with @lpw25 , the Coq stylesheet is certainly more appealing visually than the older one but I don’t find it practical as an API stylesheet. I concur with @n4323 that, for Ocaml APIs, adapting the Racket CSS would be nice (my only fear, w.r.t. the current OCaml stylesheet and that of @dbuenzl…

[image] n4323: These are laid out really nicely. Easily the most readable online documentation I have seen. What do they use? Is there a stylesheet that OCaml could steal? The CSS and underlying structure are easy to steal. I believe the tools are built by the Racket people, but we have simil…

[image] grayswandyr: the Racket doc is not very dense vertically so I imagine one may have to scroll for kilometers before reaching a given val documentation). This is what the left hand index is for.

OCaml Documentation Open Thread

Ecosystem

ashish April 19, 2018, 4:41pm 116

I’ll switch to the thread on Development of ocaml.org for further comments about that topic.

Topic		Replies	Views
Why the OCaml ecosystem is poorly documented? Community	61	3583	January 29, 2025
Making OCaml Accessible and Learnable for More People Community	63	8657	December 16, 2019
Suggestions for ocaml documentation Community documentation , ocamlorg	84	7817	July 16, 2020
2025 Documentation best practices Ecosystem documentation	36	1254	August 4, 2025
[ANN] docs.ocaml.pro : an OCaml Documentation Hub Community announce , documentation	34	4718	April 28, 2021

OCaml Documentation Open Thread

Related topics