OCaml Documentation Open Thread

My biggest problem with the documentation is that there’s no docs-wide search.

Uh, that’s the n-th website I see with OCaml docs. This one is actually pretty good!
Now, the bewildering questions I have are as follows:

  1. Why is this not linked at: Learn OCaml ?
  2. Why is the url caml.inria.fr instead of ocaml.inria.fr or even better docs.ocaml.org or something?
  3. WTF is caml and how does it relate to OCaml and how can I know if this documentation will work in the OCaml language?
  4. Why can’t we have the docs for the various standard libraries on the same website and switch exactly like you can switch between OCaml and Reason via the button in the upper right corner. From what I’ve seen the various stdlibs are quite alike and documentation easily translates between them. Can we start from the richest docs and just modify them to suit Base/Core etc.?

And yeah, that’s a huge pain. I only have google and it’s extremely heavily biased agains OCaml at least for me.

That’s a feature of the language’s semantics, and many of the other comments you have are also features of it. I wouldn’t worry about those as I’m not trying to sell Ruby (it’s an inferior language to OCaml). I’d ignore the issues of the differing language features and focus on the nature of the documentation itself.

So I’ll make a claim that will be controversial but shouldn’t be: anyone currently in the OCaml community for a long time almost certainly finds the documentation adequate. It’s a selection effect: if you found the documentation frustrating, you would have left long ago. So, you should be skeptical of the fact that you are okay with the documentation and ask instead what a naive reader, especially someone new to the language or especially even not very experienced with programming itself, might feel on reading the document.

The Ruby document has several good features. There’s a good sized general introduction, but it is easy to skip because of the page design if you’re already familiar with the content. You can click on the sidebar to get quickly to the documentation for any function, and the sidebar also typically contains links to important related parts of the language. The text is presented in a large, well selected font, the color choices are very readable, and lines are not too long on the screen. (This last bit might seem silly to some people, but it absolutely makes it easier for many people to read.) All functions, no matter how trivial, have some explanation associated with them, including mention of what all the arguments mean and what happens in error conditions. There are examples associated with almost all interesting functions, and the examples are set off with a different display style to make it easy both to read them and to skip them.

Now, I get that to you, as someone who feels comfortable with OCaml, not much of this would be of interest, but it would also not cause you any harm, but it would also, quite likely, make it easier for most people to read, easier for beginners (either to the language itself or to programming in general) to understand, etc.

The fact is that OCaml isn’t nearly as popular as Ruby. This is in spite of the fact that OCaml is a superior language. I don’t think that’s mostly about the documentation, it has a lot more to do with various accidents of history, but the documentation definitely helps a bit.

5 Likes

BTW, the purpose I had in mind for this thread wasn’t to moan but to think constructively about the sorts of things the community might interested in seeing fixed (or even willing to see fixed). I personally would be happy contributing things like documentation improvements.

4 Likes

(Oh, and many of the things I mention above as good features of the Ruby docs are also present in the documentation of other systems in various ways. Python has very nice documentation too. In another thread, someone mentioned that they really like the Erlang documentation. The Unix library documentation, in the form of man pages, is quite differently presented but also a good example of nice thorough content. I’m not saying Ruby is a particular paragon, either as a language or in documentation. Mostly I’m trying to spur discussion of what the OCaml documentation could be like.)

1 Like

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.

There are projects on the way to provide this on docs.ocaml.org. Note that if you are only interested in the documentation of the libraries you install in your opam switch, I suggest using odig this will provide you the docsets for your opam install base for your offline reading pleasure (to see a sample output of the tool head to http://docs.mirage.io/)

Aside, it is a wonderful source of amusement to me to see people (rightly) bitch when there’s no documentation and still (unrightly) bitch when it exists because they can’t be bothered to actually make the effort to look it up. 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.

1 Like

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.

I can see that being irritating.

BTW, one small suggestion I’ve remembered now, from glancing again at your uucp documentation. This is not a criticism of your stuff, it was just inspired by seeing it again.

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 in general. Many other languages combine such things, simply labeling which is which. Less clicking and more ability to see the big picture on one page.

(The Ruby docs have that and have the equivalent of such an index in the left column as well, which is quite useful.)

An experiment to change how this looks would be pretty simple to conduct since all this is machine generated from the sources. I may undertake it in a couple of months, but if anyone else cares to try it first, don’t wait for me. That said, I suspect some small changes in presentation and CSS from the documentation generator might make a significant difference in readability.

2 Likes

Absolutely, see this odoc issue and the comment linked from there.

2 Likes

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

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 the documentation / writing basic examples, and we would report on our progress in a shared conversation forum (eg. a Discuss thread).

15 Likes

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 languages.

I would happily join in on such a thing.

1 Like

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, “ppx rewriters are an advanced facility, only experts really need to understand that and they do already”, etc., but the truth is, I’d like to do some hacking on some things that use ppx (like sedlex) and mostly to date I’ve been forced to thrash around and make guesses about what I’m doing. A real ppx manual, including documentation of the modern helper libraries, would be a great thing. Indeed, I think it should be part of the main OCaml manual now that ppx looks like it’s here to stay. Yes, it’s an advanced topic, but even rank amateurs like me sometimes find themselves needing to dive in.

2 Likes

Just to make that clear, the only thing this bug prevents is apparently on macOS 10.13 to automatically open a browser tab on the package (or package index) you are interested. You can simply replace the odig doc invocation by:

open $(odig cache path)/odoc/index.html

(That said I’d still like someone to at least confirm that bug report and provide help, I currently don’t have the time to upgrade my OS).

2 Likes

I can do that with Angstrom. I don’t know if I am competent enough to not write stupid s*t, but if someone supervises me, I’d be more than happy to participate.

1 Like

I agree with your claim, and don’t think it is controversial. But I would suggest to you that it works both ways, it might be causal; one way to advance in skill as an OCaml developer is to understand what senior developers observe in the current documentation that you may be missing.

Programming language popularity is a tiresome and oft-repeated argument, that I find unconvincing. For the foreseeable future, Ruby/Python will be more popular; it is by design. The features that the language developers chose were meant, in their experience, easier for beginners to do understand. In my mind, if one were to build a model of language polarity, one would have to give that factor 10x more weight than documentation, because those choices came first.

But to echo my previous point, one reason why those languages have the documentation that they do is because of the features that they lack with respect to OCaml. In the file that you linked, consider the documentation of compact. Ruby has to give the user examples because there is no way to write:

val compact: ('a, 'b option) t -> ('a, 'b) t

which has a pretty straightforward meaning. And in an immutable, typed, language really has only one thing that the function can do.

I don’t mean to distract your creative energies. But in the interest of being constructive, I think a more worth while question is how to design and write signatures that are easier to understand.

1 Like

So I completely understand what the type signature for compact means, but I’m not able to guess what it is used for. I bet both that I can figure it out in a few minutes, and that a line or two of documentation would obviate the need for me to try to puzzle it out.

(Note that I make no claims to being particularly good at OCaml. Also, I’m on the older side, I started with Fortran in the 1970s. Being older cuts a lot of IQ points off. But this is also why I am sensitive to points where reading the type signatures is an exercise much like solving a sudoku. I don’t mind the challenge, but I’d rather be spending that time on my code…)

3 Likes

I completely agree. There aren’t many languages around which constantly have their de-facto standard libraries being switched and refurbrished, while staying rock solid in the process. But I think this is also a curse, because this situation makes OCaml harder to learn.

Yeah, but after just a very small mental leap you end up with this: angstrom/lib/angstrom.mli at master · inhabitedtype/angstrom · GitHub
Here we have one advanced and complicated thing explained with another advanced and complicated thing, whereas just a simple example would save me hours of experimentation.

4 Likes