OCaml Documentation Open Thread


#1

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.


"OCaml -- first impressions"
Development of ocaml.org
[ANN] ppxlib - Jane Street ppx infrastructure now on github
#2

To begin the discussion, I’d like to draw everyone’s attention, for example, to this pair of examples: The Jane Street “Base” Hashtbl docs versus The Official Ruby Hash documentation.

I think this pair is especially illustrative because one is pretty confusing and difficult to read, and the other is remarkably readable. Both the formatting and the content are issues here.

The OCaml document has a lot of confusing things in it that are connected to a module structure that the beginner doesn’t really care about. Explanations are terse, and no examples are given. Many functions are simply described by their type signature. There isn’t much of an introduction. The page is physically kind of ungainly and badly formatted, which makes it hard to read.

The Ruby document, by contrast, starts with a substantial introduction. Explanations are quite clear, are accompanied by examples, and there is documentation for every function. The page is quite well formatted, and is physically easy to read.

Now, interestingly, I think that a lot of this can be incrementally fixed on the OCaml side with relatively small things. Small tweaks to the documentation generators and to the CSS used could probably make things a lot prettier very fast, for example. It might also be possible to make it easier for people to help contributing content with a few small hacks to bring up appropriate sections of source on github right at the place where the documentation is presented.

However, I’m going to hang back now and let others talk a bit.


#3

Frankly I’m not sure what there needs to be discussed here. You should simply complain on base’s bug tracker. The standard library’s Hasthbl documentation is fine.


#4

This, I agree.

This, while I’m inclined to agree, I understand styling is mostly a subjective topic and it’s hard to come up with something that pleases everyone (although it should be possible to get on with something that pleases a bigger part of everyone).

The content, however, is indeed a serious issue. Communities like Ruby and Elixir loves to write docs as prose. I believe it’s something lacking in OCaml community. For Base in particular I think quite not-so-recently Jane Street hired a technical writer that hopefully could improve things on that regard, but despite that, you can always suggest an improvement to the docs on the respective repo. Perhaps we could introduce a gatekeeper (e.g. opam?) to make sure that all published packages have decent docs? I’m not sure.

The tooling is there, I think. On docs for Logs. you can see there is a section for examples at the bottom, and all the identifiers are properly documented. You can even move the example section to the top of your mli to make it render closer to the description. So it’s achievable. There’s also the Lwt API, and this page is all written in the lwt.mli file. I imagine it would render as acceptable (although less fancy) with odoc with that much of thoughtful information.


#5

Except for functor heavy code bases (where ocamldoc would rewrite its own outputs), the tooling has been here for many many years. I’m sorry but there’s absolutely no excuse not to write documentation except lazyness.

The introduction and example are at the end for a good reason: they get in the way when you want to peruse the API reference which in the end you end up doing more than reading the intro bits. Nowadays that, thanks to @trefis, we even have manuals that can be xref’d with API reference, they could even be provided on their own page.


#6

If there was nothing to discuss, we wouldn’t have beginners having problems with the docs. (And I’m such a beginner, FYI.)

I love OCaml, and I love the OCaml community, but even though people are very friendly and willing to explain things, I’d rather not have to ask people to explain things to me when good documentation would do the trick instead.


#7

BTW, @dbuenzli, I’ll note your own “Minimal Unicode Introduction”, which you have included in the docs to some of your libraries (like uucp), is a nice example of something done right in the world of OCaml documentation. That said, even for the uucp docs, I wish the CSS and the like was significantly nicer, and I wish the documentation generator put a clickable index on one side, and I could go on.


#8

Oh, and I certainly picked an extreme example for illustrative purposes, but I can point out things in the standard library hash table documentation that aren’t optimal as well. The font picked is pretty nice, but it’s a bit small on most displays. The layout and wrapping make it significantly harder to read than it needs to be. It would be nice if the introduction was a bit longer. There’s no easy clickable index. There are relatively few examples, more would be significantly nicer. The description of the functorial interface is difficult for a newcomer, and the example should probably follow an explanation. I could go on.


#9

I don’t think there’s a problem with the docs.

There’s a problem with the lack of docs for some packages but that’s a problem with the responsability of some package publishers.

The OCaml system in itself is quite well documented, so is its standard library and again all the tooling is (and has been for a long time) here to provide top notch documentation if you wish so.


#10

I would like to register a dissenting vote of general approval for both Base’s Hashtbl[1] and the standard libraries documentation. I find them sufficient for the purposes of expressing the typed manipulation of hash tables. Once I know the type signature of the data type, I can readily understand what most functions do based on their signatures, [2] and I’m starting to appreciate how JS is grouping the “interfaces” that the overall signature support. I do have 10+ years of OCaml development.

I haven’t tried to use Ruby in 5+ years. What I find confusing, besides the lack of types and odd naming[3]:

  • The documentation of some functions with the same name is grouped based upon their arguments. In some cases (for example the constructors) the logic of the separate cases is not the same and it is implicit which case is being described.
  • Somewhat surprising and non-intuitive operations: (ex. dig, rassoc, shift)
  • Inconsistent naming: (ex. eql, rassoc, to_h, to_a )
  • Not related to the documentation but the Ruby-isms (ex. ‘?’, ‘!’ in function names)
  • What is a ‘hsh’? I only sampled the first half of the 61 instances, but not-one of the just said “this is the hash object”, and why not just call it “Hash” ?

@perry I understand your frustration because OCaml is different from so many other languages. And while I’ll concede that the average OCaml documentation might not be verbose enough to compete with other languages, I would argue that that is a feature not a deficiency. Regarding your point about the aesthetics of the presentation or examples, this is open source software and I’m sure PR’s are welcome.

  1. Be brave and just call it Hash_table! This version isn’t fully backwards compatible anyway.
  2. I wish that Ctrl-F worked in general, try “-> bool”, there are spacing nits, in a “hoogle” style.
  3. Naming your Hash-Table data-structure “Hash” is needlessly confusing to beginners. This might be a cultural thing.

#11

This is a known problem, see here. @antron is working on the markup generated by odoc, I’m sure he’ll get that right.


#12

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


#13

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: https://ocaml.org/docs/ ?
  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.


#14

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.


#15

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.


#16

(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.)


#17

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.


#18

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.


#19

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.


#20

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.