My, this is a brilliant suggestion. Now that you mention it, I did notice that such narratives are sparse in OCaml world. I might be interested in sharing beginner’s perspective on Ocsigen stuff (Eliom, Lwt, etc.).
5 Likes
We’ve been working on a BuckleScript Cookbook, heavily inspired by the Rust Cookbook. Most of the examples there could easily be ported to native OCaml or jsoo. It’s a project that is very well suited for crowdsourcing and cross-pollination.
6 Likes
Ocsigen tutorials would be wonderful - as a newbie its current documentation feels quite inaccessible.
A like cannot stress enough how strongly I agree. This is also one of reasons why Real World OCaml is such a great book, you have some of these step-by-step tutorials based on sensible examples.
Four people in agreement that we should communication more; this means that we could expect four blog posts on their usage of OCaml and beginner-oriented information a library/tool that they like? 
(Please link them here, I would be happy to forward them to the OCaml reddit for example).
7 Likes
I think we’ve established interest, but acting around it is going to be a lot gradual and organic than that
But I did write something recently: An Invitation to ReasonML. It could also be called An Invitation to OCaml, but I discovered OCaml through Reason, and felt it was better branding to get front-end programmers to take notice.
I’m currently working on porting a Javascript codebase into Reason/OCaml, and I already have become that cliched better programmer because of statically typed FP. By rewriting a bunch of my imperative code into functional ones, I have gone from duct-taping stuff and hoping to never look at it again, to a clear coherent understanding of my own algorithms. I hope to have a lot to talk about once that project is completed!
9 Likes
I could have saved days of desperation if this was around earlier. Can we get this project linked from the ReasonML documentation? The FFI docs in BuckleScript manual are comprehensive, but a more example-like approach is easier to understand on first read.
Oh, if you want FFI by example I’ve got more of that. Not sure yet if it’s all that useful, but let me know what you think.
I have a few more of these low-effort learning resource experiments that can be refined and polished if they turn out to be helpful, and I’m all for integrating it with the Reason and/or BuckleScript documentation. It’s there for the taking.
They are quite useful and would be nice if we can make it part of the main documentation so that it is easy to find and is maintained.
The problem with the BuckleScript doc is that it is organized in the line of “here is a BuckleScript FFI feature, and you can use it to bind to Javascript like this”. But when I’m working on something and need to talk to Javascript in a specific manner, I want the documentation in the reverse order: “here’s a Javascript calling convention, and to get that in BuckleScript, use this FFI”.
But since I’m over the initial learning hump, I have a map of the land and can locate what I want from the documentation easily and no longer feel as strongly about it as when I began learning But I see that you have put a ton of effort into documenting these things and I’m going to try to get it merged into the main documentation soon. Thanks a lot!
2 Likes
Not so. Most PRs regard fixing up pages that already exist. However, what is really needed is whole new tutorials and mass reorganization and deletion of the content that currently exists. OCaml.org is in desperate need of more volunteers. Most PRs are accepted without much review, so please don’t hold back.
The idea of using a wiki was considered when ocaml.org was originally designed. Most people felt that PRs via github was better than a wiki. A few of the arguments against a wiki were: requires some infrastructure which is harder to maintain, the content becomes a mess unless there is some oversight (exactly what github PRs provide). FWIW, previous attempts at creating a wiki for the community have been tried at least twice and failed each time. That’s not to say a wiki couldn’t work, but I think it would be a lot of work.
3 Likes
Some OCaml documentation comments include examples, but I’m not sure this should be encouraged, and in any event, a short documentation string can’t include all relevant examples.
Clojure’s ClojureDocs might provide a nice model for provision of small illustrative examples. ClojureDocs includes a page for each common function. The page begins with the docstring for the function [analogous to (** … *) documentation comments in OCaml], followed by community-supplied examples and comments, and then community-supplied links to related ClojureDocs pages. ClojureDocs is usually my first stop for information about a Clojure function if the docstring doesn’t tell me enough, or I’ll go there simply because it’s a nice web source for docstrings. (By way of example, here’s the page for the map function.)
It’s worth remarking that many Clojure docstrings are very compressed. Some of the docstrings are very good for learning, but the core developer team seems to think of some docstrings more as reminders than as initial learning tools. But that’s OK, in most cases, given ClojureDocs and some of the other resources available. For OCaml, too, an alternative is to keep documentation comments concise but provide examples and further comments elsewhere.
Of course, more OCaml library functions should have documentation comments in the first place!
By the way, might there be some way in the furture to give access to documentation comments in a toplevel? One of the nice things about using the Clojure repl is that (doc <function-name>) will display the docstring for any function that’s in the current namespace scope. I know that comments are long gone when one is in utop, but might there be a way of creating a documentation database, both for newly-loaded ml files and libraries, and give access to it with special toplevel commands? This is more difficult than in Clojure, I guess, since you can’t store the the documentation with the function, but it would be very useful
(I’ve wondered whether the fact that OCaml provides type signatures so readily has made it easier to put off writing documentation comments, since one important part of the documentation is provided automatically. Expected types in Clojure would be mysterious without explanatory text; maybe that’s why it’s rare that doc strings are left out (except in the source code for Clojure itself!).)
Why shouldn’t be this encouraged ?
You don’t need to to put them in the doc string, but you can put them on the same page. One example is Fpath almost each functions has a link to examples since path processing is such a tricky business.
Also community crowd-sourcing documentation reminds me very much of saying that you have a wiki for documentation: doesn’t work, at all.
You just need to teach the toplevel or load a library that reads cmti files.
1 Like
There is ocp-index-top.
But it is not in the official OPAM repository yet, which means you’ll have to pin it to install it.
opam pin add ocp-index-top https://github.com/reynir/ocp-index-top.git
Thank you for linking. It’s currently broken in utop 2.0.1, but it can be worked around by using utop-full (as you know).
I think I’ll make a release today.
It depends. It’s worked as a way to provide examples for Clojure functions, as ClojureDocs shows. OCaml has a smaller community at this point, I think, but fewer examples are needed for any given function, on average, since static typing, even with polymorphism, means that each function has a more specific range of application.
Adding an example, perhaps with a few comments, is pretty easy. You don’t have to be an expert; you just have to understand that example. Maybe privileged users would periodically edit or remove the occasional unhelpful or misleading example, but in practice I don’t think that constant monitoring would be needed.
Yeah–that does sound odd. I was thinking about Clojure, where it’s good for docstrings to be short because they’re routinely displayed at the repl, and because there are other sources such as ClojureDocs for examples. Clojure’s dynamic typing, and the way in which its core functions are designed means that you might need to see several different examples to get a sense of the scope of a function’s use. A single example by itself could be misleading. (I know of only one Clojure library with long docstrings–including examples–and have found that I don’t like seeing 60 lines of text dumped to the screen in the repl when I just want to check a function’s syntax.)
Thinking about it further, I think it makes more sense to include examples in OCaml documentation comments than in Clojure docstrings, especially if it’s uncommon to display docstrings in utop. In contrast to some Clojure functions, I suspect that typically only one or two short examples would be enough to illustrate common uses of each function in OCaml.
If use of a tool like ocp-index-top becomes common, maybe it would be good to put long examples in the other comments that will show up in web documentation but not in utop.
Thanks for your other points as well.
This looks great. Thanks. I didn’t know about it.
I saw such a system in the context of php and found it to be rather dreadful. You’d get a grab bag of irrelevant examples, pointless comments or discussions, help requests, confused users, spam, bug reports, etc.
Like for programs the best documentation is the one that has been designed and good design is difficult to achieve without editorial oversight. It turns out that we already have a full infrastructure that allows to enhance documentation with editorial oversight: pull requests.
2 Likes
I’m very excited to hear that Jane Street is considering hiring a full-time technical writer for their OCaml libs. Just started using core and I definitely think that there’s a lot of utility hidden in there that isn’t discoverable right away because the auto-generated docs reflect the structure of the codebase. From a beginner’s perspective, this is an annoyance not just with core’s documentation, but with most OCaml documentation for non-trivial codebases that I have used. For example, last night I was looking for documentation on core’s List.fold function. In order to get to this from the index of the core docs, you have to:
- click on “Core”
- expand “Core__.Std0”
- expand “Core_kernel.Core_kernel_private.Std_kernel”
- expand “Core_kernel__.Std_internal”
- scroll down to “List” and click on “Core_kernel__.Std_internal.List”
- click on “List”
- expand “Core_kernel__.Core_list”
- expand “include module type of sig … end with type a t := a t with module Assoc := Assoc”
There is also no search bar (please let me know if there’s a better way). I’ve never used odoc, but I’m guessing this issue comes from it still being very young. IMO making the most-cited documentation immediately discoverable in auto-generated documentation should be a priority in the community if we want to encourage adoption of the language. Again, having never used odoc and not being familiar with its workings, I feel unable to propose a concrete solution, but if someone more familiar with the codebase could get me started on this I will gladly take a crack at implementing it myself.
2 Likes
While I’m very happy that something like “OCaml From the Very Beginning” exists at all, I agree that it would be really excellent if we could create a free example-driven resource geared towards beginners. I think this does not necessarily have to be merged with the manual (at least not right away), since I agree with @bluddy that “The manual is not a place where people go to informally learn about OCaml”. But I also agree with @ashish that “the content becomes a mess unless there is some oversight (exactly what github PRs provide)”. I bet the Haskell wiki has very good moderation, but my experience with the Emacs wiki is that it’s a sprawling mess of elisp and thoughts from a thousand different people scattered across a thousand different pages, and I do not think that PRs are a soul-draining overhead to contribution. Rust uses this library, which is basically gitbook but implemented in rust. I think gitbook (or the equivalent implemented in ocaml!) is the way to go for a project like this. While I cannot lead such an effort myself, I would love to contribute what I can.
I recently wrote a tutorial about how to use Mirage OS (IMO an example of a large OCaml codebase that has a plethora of info for academics but not so much for beginners) to host a static site. Since there seems to be a lot of agreement that beginner perspectives are needed, I’ll try to write some pure OCaml oriented articles.
1 Like
About @dudelson’s post about Jane Street’s documentation, it may be that J.S. Core has examples like this that are particularly confusing, but it’s not just an issue with Core. With Batteries, for example, you’re supposed write things like open Batteries.List, but when you got to find the documentation on List, it’s in a module named BatList. With Batteries, at least, this mental transformation is trivial once you know you have to make it, but it’s confusing for a beginner at first–it was for me. Even once I guessed that BatList contained the documentation for List, it was just a guess, and I wasn’t sure whether these modules were really identical, and was puzzled about why the same module had two names.
At this point I kind of get what’s going on, I think: There is probably a module statement somewhere that makes List an alias for BatList within module Batteries. But that’s not information that’s immediately relevant to someone starting out, and guessing or looking through the source for module aliases shouldn’t be required.
I don’t mean to pick on Batteries, or Core. I think I’ve seen the same problem with other libraries. I assume it’s the result of trying to manage modules in a rational way behind the scenes but also provide an interface to users that’s sensible and easy for them. So the source of the problem is something that’s generally a good thing.
I’m not sure what the best solution would be.
(I’m happy to be told that I’m just missing something obvious, but I don’t think I am. I’m grateful for the wide range of high-quality libraries available for OCaml, and I haven’t had much trouble using them, now that I’ve had a little bit of experience.)