OCaml.org Newsletter: January 2024

Community
1

Welcome to the January 2024 edition of the OCaml.org newsletter! This update has been compiled by the OCaml.org team. You can find previous updates on Discuss.

Our goal is to make OCaml.org the best resource for anyone who wants to get started and be productive in OCaml. The OCaml.org newsletter provides an update on our progress towards that goal and an overview of the changes we are working on.

We couldn’t do it without all the amazing OCaml community members who help us review, revise, and create better OCaml documentation. Your feedback enables us to better prioritise our work. Thank you!

This newsletter covers:

  • OCaml Documentation: New documentation has been released, and existing documentation has been improved.
  • Dark Mode: There’s been good progress on implementing the upcoming dark mode.
  • General Improvements: As usual, we also worked on general maintenance and improvements based on user feedback, so we’re highlighting some of our work below.

Open Issues for Contributors

We created many issues for external contributors. The majority of them are suitable for OCaml beginners, and we’re happy to review and provide feedback on your pull requests!

You can find open issues for contributors here!

OCaml Documentation

We released multiple new documents, most notably on Modules, Functors, Libraries with Dune, as well as a new tutorial on using the OCaml.org Playground. The documentation on Labelled Arguments, Sets, and Options has been improved.

To better understand how effective the new documentation is, we are running user tests (announced on Discuss and on Twitter/X) to compare the old documentation content on v2.ocaml.org with the new documentation on ocaml.org. A sufficient number of newcomers to OCaml volunteered to help us with this. Thanks so much!

In addition, there is an open survey that asks you to rate the new documentation in relation to the old content: We would love to have your input on this survey, even if you only drop us some numeric ratings!

Relevant PRs and Activities:

We started opening issues marked with “help wanted” to enable external contributors to help improve the docs. The response has been overwhelmingly positive, and we’re thrilled to keep this up and make the OCaml documentation truly great with your help!

Upcoming Dark Mode

In December, oyenuga17 started to implement the new dark mode on OCaml.org. Plans are to complete and activate the dark mode based on browser/operating system preferences by early March. It looks like we are on track to achieve this.

We continuously merge small patches into OCaml.org, and you can take a look at completed dark mode pages on https://staging.ocaml.org. We placed a button at the bottom of the page to toggle the dark mode on staging. (This is not going to be released. It is only a means for us to review the dark mode pages.)

Completed Pages:

General Improvements

Most Notable Changes TLDR:

  • We merged a basic documentation search feature to enable search inside the OCaml documentation. It is available on the Learn area “Overview” page! There’s room for improvements here, the most notable of which would be adding typo correction, and unifying package and documentation search in the top navigation bar’s search box.
  • A long-standing bug where wrong library names were displayed in the package documentation module tree view has been fixed!
  • The package overview page now links to a new page that lists all package versions with their publication dates.
  • The changelog is now reachable from the main landing page.
  • We now link the prerequisites of tutorials and recommended next tutorials in the YAML metadata of the tutorial’s Markdown page. This ensures that these links between tutorials will stay valid.

Many thanks go out to the many contributors who helped improve OCaml.org in January. Find them listed below!

Relevant PRs and Activities:

6 Likes