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] loxs: Why is this not linked at: Learn OCaml ? It is. The standard library documentation is part of the manual which is linked from there. Regarding the URL that’s the old OCaml website. Regarding the caml name you might want to read a bit of history . [image] loxs: Why can’t we …

[image] wokalski: My biggest problem with the documentation is that there’s no docs-wide search. As a band arm you can try to let odig generate the documentation sets on your local machine and let your OS wide search engine (e.g. recoll, spotlight, etc.) index the results.

Another possibility for docs-wide search (which is what I often do) is to use Google and tell it, with the “site:” keyword, to restrict itself to one web site. It’s not the best but it does get the job done sometimes.

[image] dbuenzli: The number of instances where I get questions about my libraries while the answers are a click away in the API docs is astonishingly high. I can see that being irritating. BTW, one small suggestion I’ve remembered now, from glancing again at your uucp documentation . This is…

[image] perry: Your documentation has the standard OCaml documentation front page that lists distinct indexes of types, values, and modules. I’ve found that there isn’t much advantage to these being on three distinct pages Absolutely, see this odoc issue and the comment linked from there.

On the specific problem of “many widely used libraries do not have adequate documentation / lack examples”, one thing we could do is organize a Documentation Sprint on a well-chosen week-end in the following months. People would be welcome to join in (remotely), pick a library, and start improving t…

Not that it’s a permanent problem, but I’ve had some trouble with odig on the Mac caused by one of the libraries it depends on. ( See this bug report .) This is of course a side issue, things like ocp-browser, Tuareg, Merlin, etc. are really amazingly good tools. I miss them when working in other lang…

[image] gasche: On the specific problem of “many widely used libraries do not have adequate documentation / lack examples”, one thing we could do is organize a Documentation Sprint on a well-chosen week-end in the following months. I would happily join in on such a thing.

BTW, another subtopic under documentation: mostly I’ve gotten around documentation problems to date for almost everything I’ve wanted to use. Sometimes it was suboptimal, but between the fact that OCaml code is so readable and people helping me, I’ve managed. The exception is ppx. I know, I know, “…

OCaml Documentation Open Thread

Ecosystem

Drup April 12, 2018, 12:54pm 22

On documentation searching: in the spirit of odig’s local documentation, you can also use ocp-browser which is a small CLI tool to search your locally installed modules.

3 Likes

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

OCaml Documentation Open Thread

Related topics