# Suggestions for ocaml documentation **URL:** \ **Category:** Community\ **Tags:** documentation, ocamlorg\ **Created:** [October 5, 2019, 2:12pm UTC](https://discuss.ocaml.org/t/suggestions-for-ocaml-documentation/4504 "2019-10-05T14:12:20Z")\ **Posts on this page:** 20\ **Page:** 1
**Author:** ![sanette](https://sea2.discourse-cdn.com/flex020/user_avatar/discuss.ocaml.org/sanette/32/1645_2.png) [@sanette](https://discuss.ocaml.org/u/sanette)\ **Post date:** [October 5, 2019, 2:12pm UTC](https://discuss.ocaml.org/t/suggestions-for-ocaml-documentation/4504/1 "2019-10-05T14:12:20Z")
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](http://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/](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](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](http://ocaml.org). Why not make it an essential part of [ocaml.org](http://ocaml.org)? Of course, this includes modernizing the css, maybe using `odoc`, or using this very nice contribution: [https://www.streamingspring.com/ocaml/docs/](https://www.streamingspring.com/ocaml/docs/), see [Modern Standard Library Documentation](https://discuss.ocaml.org/t/modern-standard-library-documentation/2880), 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/](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): - An introduction to OCaml (which could also be called “the Ocaml Tutorial”, in reference to the Python Tutorial [https://docs.python.org/3/tutorial/index.html](https://docs.python.org/3/tutorial/index.html)) - The OCaml language (or “Language reference”) - The OCaml tools - The OCaml library (this could be called “The API”, like [https://reasonml.github.io/api/index](https://reasonml.github.io/api/index)) 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. ---
**Author:** ![dbuenzli](https://sea2.discourse-cdn.com/flex020/user_avatar/discuss.ocaml.org/dbuenzli/32/18_2.png) [@dbuenzli](https://discuss.ocaml.org/u/dbuenzli)\ **Post date:** [October 6, 2019, 7:41pm UTC](https://discuss.ocaml.org/t/suggestions-for-ocaml-documentation/4504/2 "2019-10-06T19:41:51Z")
Note that `odig` allows you to browse the docsets of the libraries you install _and_ the OCaml manual using a uniform theme. For that: ```auto 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](https://b0-system.github.io/odig/doc/index.html) for an example) If you are unhappy about any of the styles, [bring your own theme](https://b0-system.github.io/odig/doc/odig/packaging.html#theme_install). ---
**Author:** ![sanette](https://sea2.discourse-cdn.com/flex020/user_avatar/discuss.ocaml.org/sanette/32/1645_2.png) [@sanette](https://discuss.ocaml.org/u/sanette)\ **Post date:** [October 7, 2019, 8:22am UTC](https://discuss.ocaml.org/t/suggestions-for-ocaml-documentation/4504/3 "2019-10-07T08:22:40Z")
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](http://ocaml.org) site. For instance the link I mentioned above by @seadynamic8 clearly has this issue in mind. ---
**Author:** ![dbuenzli](https://sea2.discourse-cdn.com/flex020/user_avatar/discuss.ocaml.org/dbuenzli/32/18_2.png) [@dbuenzli](https://discuss.ocaml.org/u/dbuenzli)\ **Post date:** [October 7, 2019, 9:53am UTC](https://discuss.ocaml.org/t/suggestions-for-ocaml-documentation/4504/4 "2019-10-07T09:53:14Z")
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](https://discuss.ocaml.org/t/central-opam-documentation-site/3886/17) (mostly scripting at that point) with the added benefit of having a resonable starting point for the mythical `docs.ocaml.org`. ---
**Author:** ![sanette](https://sea2.discourse-cdn.com/flex020/user_avatar/discuss.ocaml.org/sanette/32/1645_2.png) [@sanette](https://discuss.ocaml.org/u/sanette)\ **Post date:** [October 7, 2019, 10:23am UTC](https://discuss.ocaml.org/t/suggestions-for-ocaml-documentation/4504/5 "2019-10-07T10:23:36Z")
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](http://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 😉 ---
**Author:** ![sanette](https://sea2.discourse-cdn.com/flex020/user_avatar/discuss.ocaml.org/sanette/32/1645_2.png) [@sanette](https://discuss.ocaml.org/u/sanette)\ **Post date:** [October 7, 2019, 1:16pm UTC](https://discuss.ocaml.org/t/suggestions-for-ocaml-documentation/4504/6 "2019-10-07T13:16:09Z")
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](http://ocaml.org) and split it into parts, marginally modifying the presentation? (mainly titles and table of contents)? ---
**Author:** ![octachron](https://avatars.discourse-cdn.com/v4/letter/o/49beb7/32.png) [@octachron](https://discuss.ocaml.org/u/octachron)\ **Post date:** [October 7, 2019, 1:28pm UTC](https://discuss.ocaml.org/t/suggestions-for-ocaml-documentation/4504/7 "2019-10-07T13:28:04Z")
See [https://github.com/ocaml/ocaml.org/issues/1011](https://github.com/ocaml/ocaml.org/issues/1011) , but yes hosting the manual on [ocaml.org](http://ocaml.org) have been on the table for quite a while. ---
**Author:** ![sanette](https://sea2.discourse-cdn.com/flex020/user_avatar/discuss.ocaml.org/sanette/32/1645_2.png) [@sanette](https://discuss.ocaml.org/u/sanette)\ **Post date:** [October 8, 2019, 7:57am UTC](https://discuss.ocaml.org/t/suggestions-for-ocaml-documentation/4504/8 "2019-10-08T07:57:14Z")
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 ? ---
**Author:** ![octachron](https://avatars.discourse-cdn.com/v4/letter/o/49beb7/32.png) [@octachron](https://discuss.ocaml.org/u/octachron)\ **Post date:** [October 8, 2019, 8:36am UTC](https://discuss.ocaml.org/t/suggestions-for-ocaml-documentation/4504/9 "2019-10-08T08:36:05Z")
I am not sure what you mean by obtaining a layout similar to odoc: odo > [@sanette](#): > > For the last part, switching to odoc would be good. 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`. ---
**Author:** ![XVilka](https://sea2.discourse-cdn.com/flex020/user_avatar/discuss.ocaml.org/xvilka/32/5334_2.png) [@XVilka](https://discuss.ocaml.org/u/XVilka)\ **Post date:** [October 8, 2019, 8:53am UTC](https://discuss.ocaml.org/t/suggestions-for-ocaml-documentation/4504/10 "2019-10-08T08:53:38Z")
@sanette there are some efforts to [integrate `odoc` with `mdx`](https://github.com/realworldocaml/mdx/issues/17) and [generating PDF with `mdx`](https://github.com/realworldocaml/book/issues/3020#issuecomment-536285431), 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](https://github.com/ocaml/ocaml/issues/8718) in the OCaml manual, but sadly no time to do that yet. ---
**Author:** ![dbuenzli](https://sea2.discourse-cdn.com/flex020/user_avatar/discuss.ocaml.org/dbuenzli/32/18_2.png) [@dbuenzli](https://discuss.ocaml.org/u/dbuenzli)\ **Post date:** [October 8, 2019, 10:02am UTC](https://discuss.ocaml.org/t/suggestions-for-ocaml-documentation/4504/11 "2019-10-08T10:02:51Z")
> [@octachron](#): > > 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. I still hope upstream will at a certain point give a bit more thought about [this message](https://github.com/ocaml/ocaml/pull/8835#issuecomment-515595625). ---
**Author:** ![wokalski](https://sea2.discourse-cdn.com/flex020/user_avatar/discuss.ocaml.org/wokalski/32/38_2.png) [@wokalski](https://discuss.ocaml.org/u/wokalski)\ **Post date:** [October 8, 2019, 10:18am UTC](https://discuss.ocaml.org/t/suggestions-for-ocaml-documentation/4504/12 "2019-10-08T10:18:02Z")
It would never pass, but hypothetically HTML pages could be converted to PDFs automatically. ---
**Author:** ![sanette](https://sea2.discourse-cdn.com/flex020/user_avatar/discuss.ocaml.org/sanette/32/1645_2.png) [@sanette](https://discuss.ocaml.org/u/sanette)\ **Post date:** [October 8, 2019, 12:50pm UTC](https://discuss.ocaml.org/t/suggestions-for-ocaml-documentation/4504/13 "2019-10-08T12:50:50Z")
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. ---
**Author:** ![octachron](https://avatars.discourse-cdn.com/v4/letter/o/49beb7/32.png) [@octachron](https://discuss.ocaml.org/u/octachron)\ **Post date:** [October 8, 2019, 1:05pm UTC](https://discuss.ocaml.org/t/suggestions-for-ocaml-documentation/4504/14 "2019-10-08T13:05:36Z")
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. ---
**Author:** ![dbuenzli](https://sea2.discourse-cdn.com/flex020/user_avatar/discuss.ocaml.org/dbuenzli/32/18_2.png) [@dbuenzli](https://discuss.ocaml.org/u/dbuenzli)\ **Post date:** [October 8, 2019, 1:25pm UTC](https://discuss.ocaml.org/t/suggestions-for-ocaml-documentation/4504/15 "2019-10-08T13:25:51Z")
> [@octachron](#): > > 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. ---
**Author:** ![XVilka](https://sea2.discourse-cdn.com/flex020/user_avatar/discuss.ocaml.org/xvilka/32/5334_2.png) [@XVilka](https://discuss.ocaml.org/u/XVilka)\ **Post date:** [October 8, 2019, 3:38pm UTC](https://discuss.ocaml.org/t/suggestions-for-ocaml-documentation/4504/16 "2019-10-08T15:38:51Z")
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. ---
**Author:** ![dbuenzli](https://sea2.discourse-cdn.com/flex020/user_avatar/discuss.ocaml.org/dbuenzli/32/18_2.png) [@dbuenzli](https://discuss.ocaml.org/u/dbuenzli)\ **Post date:** [October 8, 2019, 8:05pm UTC](https://discuss.ocaml.org/t/suggestions-for-ocaml-documentation/4504/17 "2019-10-08T20:05:48Z")
@xvilka epub is HTML in hiding 😉 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](https://b0-system.github.io/odig/doc@odig.dark/ocaml/index.html) 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](https://github.com/b0-system/odig/blob/5ccf45418df0805f3845061d9540c70c91166280/src/odig_odoc_page.ml#L45-L71) 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. ---
**Author:** ![octachron](https://avatars.discourse-cdn.com/v4/letter/o/49beb7/32.png) [@octachron](https://discuss.ocaml.org/u/octachron)\ **Post date:** [October 9, 2019, 8:13am UTC](https://discuss.ocaml.org/t/suggestions-for-ocaml-documentation/4504/18 "2019-10-09T08:13:46Z")
@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. ---
**Author:** ![sanette](https://sea2.discourse-cdn.com/flex020/user_avatar/discuss.ocaml.org/sanette/32/1645_2.png) [@sanette](https://discuss.ocaml.org/u/sanette)\ **Post date:** [October 9, 2019, 8:45am UTC](https://discuss.ocaml.org/t/suggestions-for-ocaml-documentation/4504/19 "2019-10-09T08:45:22Z")
this is completely in line with my initial suggestion to split the manual, so I plus this too. ---
**Author:** ![dbuenzli](https://sea2.discourse-cdn.com/flex020/user_avatar/discuss.ocaml.org/dbuenzli/32/18_2.png) [@dbuenzli](https://discuss.ocaml.org/u/dbuenzli)\ **Post date:** [October 9, 2019, 7:27pm UTC](https://discuss.ocaml.org/t/suggestions-for-ocaml-documentation/4504/20 "2019-10-09T19:27:09Z")
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](https://b0-system.github.io/odig/doc@odig.dark/afl-persistent/index.html#package_info) 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`, `README`s 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](https://erratique.ch/software/odig/doc/packaging.html). 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](https://erratique.ch/software/brzo/doc/manual.html) [two](https://erratique.ch/software/b0caml/doc/manual.html) examples I recently wrote. Let me know if you need further info and/or help. [Next page](https://discuss.ocaml.org/t/suggestions-for-ocaml-documentation/4504.md?page=2)