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.
2 Likes
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 Likes
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.
3 Likes
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.
2 Likes
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.
2 Likes
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.
1 Like
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.
1 Like
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.
1 Like
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.
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.
- Be brave and just call it Hash_table! This version isnāt fully backwards compatible anyway.
- I wish that Ctrl-F worked in general, try ā-> boolā, there are spacing nits, in a āhoogleā style.
- Naming your Hash-Table data-structure āHashā is needlessly confusing to beginners. This might be a cultural thing.
1 Like
This is a known problem, see here. @antron is working on the markup generated by odoc, Iām sure heāll get that right.
2 Likes
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:
- Why is this not linked at: Learn OCaml ?
- Why is the url
caml.inria.frinstead ofocaml.inria.fror even betterdocs.ocaml.orgor something? - WTF is
camland how does it relate toOCamland how can I know if this documentation will work in the OCaml language? - 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