OCaml Documentation Open Thread

[dbuenzli]

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

[Drup]

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.

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

[perry]

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.

[perry]

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

[perry]

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.

[dbuenzli]

@perry

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

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

[loxs]

@gasche

pick a library, and start improving the documentation / writing basic examples,

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.

[leonidr]

@perry

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.

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.

@perry

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.

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.

[perry]

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…)

[loxs]

@leonidr

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.

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.

@leonidr

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

@leonidr

which has a pretty straightforward meaning

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.

[wokalski]

Thanks! ocp-browser is exactly something I wish was built into the docs.

[perry]

BTW, I thought about compact for a couple of minutes and I indeed can now guess what it would be used for. However, stack too many of these “just take a minute and think about it” moments together and learning a library becomes quite slow indeed. (And again, although I’m clearly slower than most of the people here, I suspect I’m more representative of what many programmers interested in adopting OCaml might be like. And let me repeat, for about the 800th time, that I really like OCaml. It’s really pleasant compared to many other alternatives I’ve tried.)

[Drup]

@loxs

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.

This is clearly just the applicative functor operator on t. What’s the problem? Every OCaml programmer should know that.

cough cough

To be fair, no amount of documentation will help you on that one. You need concrete examples on how it’s used to understand why it’s useful.

[loxs]

Yeah, if we do the DocJam weekend, I indent on dissecting the calculator example in the README and maybe extending it a bit. I think that would be extremely useful for future users of Angstrom and I am to some extent competent enough to explain maybe half of the library at this point.

[perry]

@Drup

To be fair, no amount of documentation will help you on that one. You need concrete examples on how it’s used to understand why it’s useful.

This is one of the reasons I was suggesting that documentation should have examples in line. It helps a lot.

[Drup]

Absolutely, and I agree. What I think most libraries lack are not really text describing the functions, but small approachable examples.

[bobbypriambodo]

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

Bumping in case someone missed it—I think this is a brilliant idea and worth to try. If everyone agrees, perhaps we can start use this thread (or create another) to work out the details?

[BikalGurung]

Indeed this is a good idea. I think I would start out with the ocaml stdlib.

[BikalGurung]

Also with regards to formatting, presentation, ui of the ocaml.org website, could this perhaps be of any value/use? https://github.com/facebook/docusaurus

This seems to be adopted by both bucklescript/reasonml already.