From the OCaml survey and several discuss threads, it seems clear that documentation is an important issue in OCaml, especially with PPXs. I’m pleased to announce two improvements on this side: the publication (last summer) of our new “Preprocessors and PPXs” guide on OCaml.org, and the vast enhancement of the ppxlib documentation (very recently).
The ocaml.org guide is targeted at newcomers who don’t know what a PPX is, nor how to use them.
The ppxlib’s documentation is targeted at PPX authors, as well as PPX users who want to know more about the advantages, and what’s under the hood, of ppxlib.
The improvements in the ppxlib’s documentation are:
- More content: many new sections and explanations were added.
- More discoverability: Instead of being spread in many API pages, the “general” documentation is gathered in
.mldpages focused on a specific topic, such as “matching code”, “good practices”, etc. API pages are focused on the API itself, with links to the relevant sections of the manual. - Thanks to
odoc, I could also easily add many links from the manual to the API items. - Many code snippets did not compile, due to programming typos or outdated API. Those were corrected and improved.
- The API landing page was very difficult to navigate. It is now more organized, with sections, and docstrings for every toplevel modules.
The manual can still be improved in many ways. There are many sections that could be added or improved. A global navigation bar would help a lot the navigation in the mld pages. I will also add soon a check that code snippets don’t go outdated, using mdx (on .mli first, but also on .mld as soon as the relevant mdx PR is finished and merged!).
Overall, writing documentation has been very smooth for me. I would encourage the community to contribute to the documentation effort: PRs for improvements of ppxlib’s docs are warmly welcome, and I’m sure that’s the case for many packages! It is really a killer feature to have all docs centralized on ocaml.org, and odoc is a great tool for writing both an API and a manual with interconnected links; Let’s make the best use of this!
Thanks a lot to @pitag and @professor.rose for the very valuable and comprehensive reviews, respectively on content and form, which highly improved the quality of the documents! Thanks also a lot to Tarides and Jane Street for sponsoring me to work on this task!
