I vaguely remember seeing some sort of comments to the effect that a renovation of the base OCaml documentation was being contemplated, but after searching I’ve not been able to find any mention of it, so I may have been mistaken. Am I imagining having heard about this?
(The upcoming migration of the Coq documentation to Sphinx reminded me to ask about this.)
I am not sure which “documentation pages” you are talking about.
There is the official OCaml Manual, the reference documentation, which I personally think is surprisingly good. I am not aware of a big revamp plan, although @octachron would be the person to ask about changes to the manual (he has been contributing a lot of nice things to it in the last few years). On the other hand, it has been mentioned a couple time that the web output is currently ugly, so I guess that some people may be willing to work on improving this – this doesn’t need to be an invasive change.
There are some user-contributed tutorials on ocaml.org that are very unequal in quality and would need people willing to work on them (either migrate the information away into better places, or revamp them; personally I think the first option would be better)
The documentation-generation tool for .mli files, ocamldoc, has acknowledged limitations, and there exists a plan to implement a better one that has been running since 2013 (opam-doc, now odoc). The progress on this is irregular, my understanding is that odoc is already usable today – for example some version of it powers docs.mirage.io – but as far as I know it hasn’t been officially released and there is little information online about how someone not involved in its development may want to use it. (While ocamldoc is understood to have fundamental limitations, it is reasonably well maintained and evolves in tandem with new OCaml features.)
My purely personal guess is that the OCaml manual will stay mostly the same, but get a more modern web design, that the ocaml.org tutorials will be removed (how much of the work poured into them will be lost depends on whether people are willing to volunteer work), and that odoc will eventually (in some unpredictable amount of time) become the standard documentation generator – with public documentation generated at a centralized opam-repository level instead of documentation pages being hosted locally (or not hosted at all) by each package author.
One I can remember is Anil and Daniel discussed briefly about having a centralized docs here:
Is that a wishlist item or is it something being actively worked on? It would certainly help with readability.
I would be curious about what docs.ocaml.org is intended to contain. I think that is what I vaguely remember.
It is something being slowly worked on.
I’m curious what the plans are. This is the sort of thing where newcomers like me can be of help — converting documents from one form to another often requires only limited experience.
Since the html version of the manual is mostly generated from latex source files and ocaml interface files; there is not real need for migrating or converting the documents themselves. Currently, in term of manual infrastructure, my mostly non-ordered todo list looks like:
I am not sure if any of this task is newcomers friendly, even more so when compared to writing documentation: for instance, on error or warning messages; or about using lazy values, ephemerons or the Format module.
Ah, too bad. But if something that isn’t very OCaml-knowledge specific, like working on nice CSS styling, comes up, please do mention it.
Hello, you can see currently filed issues on the bug tracker to get an idea of what people want to see improved: https://caml.inria.fr/mantis/view_all_bug_page.php (set the ‘Category’ to ‘ocamldoc’ and then click ‘Apply Filter’).
For example, here’s an (in my opinion) interesting case where the HTML output is fairly clumsy and not very accessible: https://caml.inria.fr/mantis/view.php?id=7634
I brought up the topic of a design refresh a while back, I haven’t had time to work on it recently though. If you’re curious: Proposal: ocamldoc should generate a table of contents in each module page
@yawaramin, I’m very fond of the documentation style one sees for Ruby and Python.
Examples: the Ruby string module documentation and the Python time module documentation.
The formatting in both of those is very clean and easy to read. The typesetting shows indicates very naturally to the reader what is important and what isn’t, where you should start and end reading any given topic, etc. I realize many people don’t recognize the importance of good typography in making it easier to read documentation, but it has major effects on usability.
Similarly, Paul Steckler and others are working on a conversion of the Coq documentation to Sphinx (which is the system used for Python’s documentation). Here is what it looked like before, which I find rather unreadable. Here’s what it looks like converted, which I think is vastly nicer.
Well this is rather easy, and interested people should not hesitate to contribute.
I started working on this in the following Pull Request #1209. There are things to improve in the manual rendering before we can merge this (and the improvement may require more hacking, so beginners are welcome but this may or may not turn out to be easy), but continuing the work of porting code example in the manual to the new caml_example environment is rather simple.
There is information in manual/README.md on how to build the manual and how to use the caml_example environment. Any further question can help improve this documentation.