Suggestions for ocaml documentation

Exploring this website I found some interesting threads about the problem of attracting new programmers to Ocaml; while these threads often end up raising the temperature, they’re not uninteresting, and one has to face the reality. One of the suggestions was to modernize the documentation. I totally agree.

First of all, finally moving from the 1990-styled inria web site to the newer ocaml.org was a great decision. One can dislike the design of it, but at least it doesn’t look so outdated, and this is very important.
But there is still the problem of the documentation. To my opinion, the https://ocaml.org/docs/ page should be improved, as it does not advertise enough the existing doc, and is probably disappointing for newcomers. Here are some suggestions.

  1. The front page https://ocaml.org says “Documentation
    Install OCaml, look up package docs, access the Manual, get the cheat sheets and more.”. This is appealing. But once you are on the Doc page, the info is quite scattered; it’s not so clear how to access these. My suggestion is to have a large menu covering the most important aspects.

  2. To my opinion, the “Ocaml Manual” is by far the most important piece of information, at least for me, this is the one I’m visiting the most often. But it’s not even part of ocaml.org. Why not make it an essential part of ocaml.org? Of course, this includes modernizing the css, maybe using odoc, or using this very nice contribution: https://www.streamingspring.com/ocaml/docs/, see Modern Standard Library Documentation, but also more:

  3. The ocam Manual contains too much information packed into a single “component”. It is too bad that such a nice document, with chapters that I often realized I forgot, or new chapters I didn’t notice, is not better advertised. My suggestion is to have the whole https://ocaml.org/docs/ page in dedicated to it, but also to split its contents into separated, more accessibles components (it’s easy, they are just the various parts of the manual):

These are the four blocks that should appear prominently on the doc page, instead of the current blocs with links, videos, books advertisements, etc.

A final word; there will be maybe positive or negative reactions to this post; or maybe none. But from what I have read it seems that most of the community agrees on the importance of improving the documentation somehow. So, let’s not waste too much time in discussions; in this post I’m only concerned about appearance, and not content, so it should not be too delicate to handle. I’d be happy if someone took the decision to do something quickly, be it or not along the lines of my suggestions above, be it or not approved by the “majority”. If we wait another 5 years, then we will be 5 years late in terms of trends and design, etc. At this point I’m totally ignorant about how to concretely help modifying the website, but I’m happy to give a bit of my time to help.

10 Likes

Note that odig allows you to browse the docsets of the libraries you install and the OCaml manual using a uniform theme. For that:

opam install odig ocaml-manual
# choose a theme from the list except odoc.default.
odig odoc-theme list 
odig odoc-theme set THEME
# browse the manual (see the list of links on the right)
odig doc 

(see here for an example)

If you are unhappy about any of the styles, bring your own theme.

2 Likes

thanks for the links. Note that my personal taste in terms of design is not relevant; what is important is that the manual looks modern and is well integrated in the ocaml.org site.

For instance the link I mentioned above by @seadynamic8 clearly has this issue in mind.

1 Like

I don’t know what “modern” means but in any case if the problem is a manual on ocaml.org that looks like it, this could be done by creating an odig theme for it and and follow a very simple action plan (mostly scripting at that point) with the added benefit of having a resonable starting point for the mythical docs.ocaml.org.

yes exactly. Well my suggestions are not as ambitious as the thread you mention, but to start with: split the ocaml manual in 4 (or 5) documents, display them prominently on ocaml.org/doc, using a unified theme. This is also an opportunity to clean them up a little bit, so that they don’t look so much like a technical report translated from LaTeX :wink:

I’m glad to see that there does not seem to be a strong opposition against these ideas.
So, now, where to start?

First of all, is this OK with INRIA that we host the manual on ocaml.org and split it into parts, marginally modifying the presentation? (mainly titles and table of contents)?

See https://github.com/ocaml/ocaml.org/issues/1011 , but yes hosting the manual on ocaml.org have been on the table for quite a while.

what do you suggest would be most efficient for manipulating the manual?
Part of it is in extended LaTeX (etex) and part of it is generated by ocamldoc.
For the last part, switching to odoc would be good. For the first, part: how to obtain a layout similar to odoc ?

I am not sure what you mean by obtaining a layout similar to odoc: odo

Switching to odoc is not that simple because it does not support non-html backend which are needed for the pdf version of the manual.

If you want to edit the rest of the manual css, the right file is manual/manual/macros.hva.

@sanette there are some efforts to integrate odoc with mdx and generating PDF with mdx, which would be helpful for a better RWO2 and odoc-generated content, but will not help with the existing LaTeX sources of the OCaml reference manual. Moreover, there are still missing pieces here and there to make them all work together on the real code and produce PDF successfully, so it’s one of the possible areas where some help would be appreciated. Speaking about the subject, some time ago I opened an issue about enabling syntax highlighting in the OCaml manual, but sadly no time to do that yet.

I still hope upstream will at a certain point give a bit more thought about this message.

It would never pass, but hypothetically HTML pages could be converted to PDFs automatically.

maybe that’s a small fly in the ointment, but is this really useful to produce a PDF file?
I’d rather concentrate on good html+css.

You are all very welcome to focus your effort and work on the html side of the manual.

I have personally no plan to drop support for the pdf version of the manual.

Just to make things clear. I never suggested to drop the PDF version of the manual. I suggested the API documentation of the libraries distributed with OCaml should not be part of the manual.

Reading PDF is still as relevant as ever, especially if you have a tablet computer or some kind of electronic book device. You still can add the notes, bookmarks, etc, as with paper before. This usage scenario is impossible in case of HTML/CSS. So I am all for keeping PDF too, just sprucing it up.

@xvilka epub is HTML in hiding :wink: but again I doubt it’s very useful to have the stdlib API in the PDF if you don’t have the rest of the libraries you are using with you.

In any case my gripe is not really having the API in the PDF or not. My gripe is that no attention is being paid upstream to this OCaml package page and structure.

Yet this is where the basic types and links from other packages’ API docs towards OCaml’s stdlib and libraries like Unix will link to by the virtues of the excellent work done by the odoc developers. They will not link into the manual own’s rendering of the API because that one lives in its own world (not to mention that it’s actually nice for developers spending so much time in front of their screen to let them see API docs with the style they wish).

So despite a little bit of ad-hoc work done specially for it in odig's code to try to improve it, that page is doomed to remain completly messy and unusable. Besides end-user will likely miss important information (e.g. win32 compabitility of the Unix module) that is hidden away in the API preambles of the manual where their clicks are unlikely to lead them.

With odoc and .mld files we now have excellent tools to move (and who knows maybe improve) the information from part IV of the manual and root it firmly in the eco-system’s odoc API hypertext which is where it is to be naturally found and read.

2 Likes

@dbuenzli, If I understand correctly, what you really want is to have the part IV of the manual available in the mld format and installed as part of the standard distribution of the compiler? This sounds eminently doable. We could start by having a small .mld+extensions to .tex translation program and try to switch the manual latex sources to mld.

this is completely in line with my initial suggestion to split the manual, so I plus this too.

Basically yes though personally I’m not sure it’s worth adding more programs to the already involved manual construction upstream. But if that’s the way upstream prefers to proceed why not.

There are different ways to go about this. But it would be at least nice to provide an index.mld (installed in $(DOCDIR)/odoc-pages/index.mld) for the package’s landing page with a section for each of the libraries with a short preamble and its curated list of modules.

If the package’s opam file is installed in $(LIBDIR) you get a bit of information automatically added at the end of that page aswell (see here for an example). E.g. direct links to the bug tracker and the home page of the project, authors etc.

Another thing that would be nice to have is to install LICENSE, READMEs and Changes in $(DOCDIR). This makes them automatically hyperlinked from the package page and available e.g. via odig changes ocaml. The full packaging conventions are described here.

If there is a lot of documentation or a manual for a given library it’s possible to offload it to a dedicated library.mld page to install in $(DOCDIR)/odoc-page/library.mld. It’s your duty to link to it from the index.mld page or from the API documentation. However I think some of the current information in LaTeX could simply be pushed into .mli files, possibly in a dedicated section at the end of the module (e.g. I’m thinking about the win32 compat. of the Unix module).

It could be tempting to simply translate part IV into a full .mld document though I’m not sure what this would give in practice. At least I don’t think it would be good to have it as the index.mld page which should allow efficient access to the module docs. If you want examples of more extended .mld manuals here are two examples I recently wrote.

Let me know if you need further info and/or help.

1 Like