I definitely don’t think it’s just an issue with core, as I’ve had similar experiences with other libraries. In general my issue is that I have to dig through the docs in order to find stuff that I’m sure lots of people have to reference all the time. Core’s List module is just one example. By enumerating above the steps I took to find the documentation, I was hoping to make the point that right now browsing OCaml docs is a lot like going through the source itself. But as a user of the library, I don’t care how its modules are laid out, I just want the docs to be organized in a logical way so I can find things easily. Odoc only hit 1.0.0 a few months ago, and I’m sure doing anything other than generating docs by walking the source tree is not a priority right now. I certainly don’t expect auto-generated docs to get super user-friendly right away, but I do think that if it takes a beginner 8 steps to find the function they’re looking for, there’s room for improvement there.
Odoc only hit 1.0.0 a few months ago, and I’m sure doing anything other than generating docs by walking the source tree is not a priority right now.
Odoc does much more than that. It is specifically designed to try to present the intended interface rather than the way in which the interface has been constructed. It’s already doing a huge amount to present the view of core you see in those docs. Core is actually made up of modules called e.g. Core__Map and Core__List and all references between them are of the form Core__.Foo. These modules are then aliased within a module Core so that they can be referred to as Core.Foo. Odoc sucessfully hides all of this to present only the Core.Foo versions with references between them appearing as just Foo rather than Core__.Foo.
However, as you point out, the result is still not particularly readable. This is because doing better requires some assistance from the core authors. Odoc cannot guess that it would be better to inline the include Std0 – it needs to be told with an annotation. Such annotations haven’t yet been added to core but they have been added to the documentation of base, and if you look at the documentation for base it is fairly readable. base is probably also a better starting point than core at this point anyway.
I don’t want my previous message to give the impression that odoc is all finished. There is still a ton of work to do on odoc. I just wanted to point out that odoc is already pretty good at massaging documentation so that it appears as intended, and in cases like the core index it only needs a few annotations to make things much more readable.
I can’t say that I disagree. In general, I think that there’s not enough respect these days for the value of well-curated information–for example, what good book publishers do in choosing authors and projects and helping authors to produce good, well-edited books, and what good news organizations do in bringing together and supporting good journalism.
The other day I asked on the Clojure Google group how and by whom ClojureDocs is managed. It sounds like there’s not much management that goes on. You have to sign up to add examples, and that also gives you the right to edit others’ examples. ClojureDocs has the potential to be a horrible mess, but it’s not. It seems very different from the PHP site you described. So what’s the difference? Does Clojure make people virtuous and thoughtful, or is it only attractive to virtuous and thoughtful people? I think that’s very unlikely.
My speculative idea is that in a very popular language, the foolish and annoying people, while a small percentage of all users, are still large in number in an absolute sense. They can do foolish and annoying things to a site which persist unless someone spends the time to correct their errors. Clojure is relatively unpopular, so an uncurated examples site works. If Clojure were more popular, ClojureDocs would have to have someone evaluating submissions, as pull requests or using some other system.
If that’s correct–and I don’t know whether it is–then an uncurated example site would probably work for OCaml in the near future, but perhaps not in the long term. However, a curated site–e.g. using pull requests–could work both now and in more distant future without change.
Is there any advantage to having an uncurated site, if it will not be overrun by foolish and annoying people? I think there is an advantage, but it’s not clear how great the advantage is: I feel that an uncurated site can (i) feel more welcoming to intermediate users and (ii) may have a greater number of useful examples. It also (iii) means that no one has to evaluate pull requests.
(In support of (ii), I can only say, fwiw that I have contributed what I believe are good exampes to ClojureDocs, and I’m not sure I would have done so as readily if I had to submit pull requests–even though I’m quite comfortable submitting pull requests when I want to contribute source code to a project. An example is a small thing, so the less the trouble it is to contribute, and the more quickly it appears, the more likely I am to contribute it.)
It should be clear that I’m not really arguing for one side or the other.
I second the need for much better documentation accompanied with examples for both OCaml and its libraries, without doubt.
For example, I have been learning Elixir and OCaml at the same time for the past weeks, and the quality of the documentation for the working programmer between these two communities is abyssal. Take a look at this documentation page from the Ecto Library (for database access) to see what I mean, and compare it for example with the scarce examples of PG’OCaml.
The best example of documentation in the OCaml community is that of Ocsigen, which perhaps rivals with that of Elixir’s Phoenix Framework. I would like to see more libraries documented like these two, or at least, with much more than a simple, most of the time, evident explanation of what each function does (hence useless, as most of the time the explanation just reads directly from the function’s type).
A good example of quality documentation in the OCaml community is that created by Daniel Bünzli for the libraries in Erratique’s site. Unfortunately, the documentation of many libraries in OPAM repository do not have the extent, detail, and practical guidance as those of Daniel’s. (Good work Daniel).
Believe me, that I just took the time to write this because I really like OCaml, and would like to see it to widespread.
Hope this helps.
Agreed wholeheartedly. You may be interested to hear that there are works going on strong to make documentation better: I’ve heard stories of a centralized docs website (think Elixir’s Hexdocs) and improvements on tools usability (odoc in particular) that are in progress. 
That is good news. Everything that reduces the friction when using OCaml’s tools and libraries is welcome and decisive for its widespread.
Who said erlang? Documentation quality differs from project to project and seldom depends on language itself. What’s really lacking is centralized doc resource, like http://docs.mirage.io/
Actually, even this bare-bones Elixir doc page is more discoverable than the default ocamldoc/odoc-style pages we have today … you have the package name and version, a TOC and a search box on the left, so you always know where you are and where you can go. And the left pane is even hideable.
It’s true that documentation quality varies, which @mguimas aready agreed, but the Elixir ecosystem certainly seems to encourage and enable good documentation.
I kind of find it funny I’ve been writing a lot of Erlang lately and a lot of it’s usability problems are the same, no doc sites, a lot of the times you might be pulling code straight from github, different people use different build tools.
The inherent language features of Elixir fall pretty short documentation wise, hexdocs is just user friendly, and I notice a lot of developers not bothering to use typedefs, which should be verbotten.
So Exlixir projects tend to wind up having this long winded read the docs style textual detail on every function like you would see in python.
Like deciphering Ocaml documentation is easy, but the searching would be nice every other modern PL I’ve used besides erlang and ocaml can be searched.
I don’t think we should make “OCaml Accessible and Learnable for More People”.
We should make it an even better and powerful language than the
awesome programming language it is right now in the hands of the right people.
And, if that makes it even more elitist, well, that’s life! 
OCaml is a superb language for someone who has no prior programming experience and in my humble opinion does its community put very low focus on this niche. 
This is of course since this community is occupied by very experienced programmers who show very very less interest into creating tutorials for complete newbies until.
Python grew to one of the most popular languages by providing a an environment to grow for children and other newbies.
In OCaml, this is very much not the case, same as in very most other languages.
This is especially remarkable since the language itself is very suitable to completely new programmers by its declarative and concise syntax, the high level of expressiveness and the inferred type system.
In order to show interested people, which kinds of tutorials I consider as useful, take this as an example: https://www.youtube.com/watch?v=hsTmLhnzRhE&list=PLEoMzSkcN8oNiJ67Hd7oRGgD1d4YBxYGC
I see the following things as the benefits:
- The source data gets created in the application itself.
Which means you can focus on the actual language, instead of other environments like the web, query languages or so.
-
I see that domain driven design let us recall on which purpose is the application build around anyway, it helps to avoid issues thanks to the type inference and so on
-
He actually implements a real world application
This is for me the most important point, since I see pseudocode as poison when it comes without an real world example combined
This tutorial builds up on the same project in the following episodes and introduce new aspects of the language very smooth.
What is your opinion?
I am still not sure whether this was intended to be tongue in cheek. I guess that’s what the emoticon implies?
Either way I’m thankful that so many in the OCaml community are welcoming to newbies. I selfishly want the community for this awesome programming language to be larger, because that means more libraries, more tools, tested in more contexts and, ultimately, potentially, an even better and more powerful language more quickly. (Sure, popularity can have negative consequences in some circumstances. I don’t see the community allowing that to happen.)
If you like to do that, you can use this as basement, since I think its quite nice as language documentation:
https://en.m.wikibooks.org/wiki/F_Sharp_Programming
Its mostly about changing things like ‘Units of measure’ and a couple of renames so I hope its possible to adopt this quite fast. 
In general, I think its quite nice written, while again: I see such documents alone a bit too less for complete beginners.
Its more like something that you use to look up. 
Interesting resources for newcomers:
https://try.ocamlpro.com/
https://rosettacode.org/wiki/Rosetta_Code
The latter allows to see a solution to a problem in several programming languages. Many people have contributed OCaml solutions apparently.
The Rust Cookbook link appears to be dead - I think it should be https://rust-lang-nursery.github.io/rust-cookbook/
Seems I can’t edit posts this old, but thanks for the correction!
It is also notable, that the Real World OCaml book had a lot of small updates and corrections since. You can follow development in their repositories. Pull requests are always welcome 