WIP INTERNAL TO OCAML.ORG TEAM - DO NOT SHARE

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 has 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:

• In Progress:
  • Maps
  • Higher Order Functions
• In Review (internal):
• In Review (community):
  • File Manipulation (see Discuss Thread)
  • Polymorphic Variants (see Discuss Thread)
• Published:
  • Sets
  • Options
  • Modules, Functors, Libraries With Dune (see Discuss)
  • Labelled Arguments
  • The OCaml Playground by @The-Amoghavarsha
  • Running Commands in an opam Switch
  • Mutable State / Imperative Programming (see Discuss Thread)
  • Announcement on Discuss: New Tutorials on Basics of OCaml
  • Basic Data Types (see Discuss Thread)
  • Functions and Values (see Discuss Thread)
  • Installing OCaml (see Discuss Thread)
  • A Tour Of OCaml (see Discuss Thread)
  • Your First OCaml Program (see Discuss Thread)
  • Introduction to opam Switches
  • Fix Homebrew Errors on Apple M1
  • Operators
  • Error Handling (see Discuss Thread)
  • Arrays (see Discuss Thread)
  • Sequences (see Discuss Thread)
• Other Activity:
  • Fix code example in Values & Functions tutorial by @cuihtlauac
  • Improve 'Managing Dependencies with opam' by @sabine
  • (doc) Mention dune-release opam package in "Publishing a Package" by @sabine
  • Add how to generate odoc .mld documentation pages with Dune to the "Generating Documentation With odoc" by @sabine
  • Prepend opam exec -- on all dune commands by @sabine
  • Mention record update syntax by @srj31
  • Fix Getting Started documentation by @akindofyoga
  • Fix wording on Getting Started page by @akindofyoga
  • Fix typos in Your First OCaml Program tutorial by @cuihtlauac
  • (doc) Fix small typo on Getting Started page by @akindofyoga
  • Remove links to V2 in docs by @cuihtlauac
  • (doc) Some misc minor doc nits by @heathhenley
  • Code test for Set V2 Tutorial by @christinerose
  • (doc) Remove Functional Programming document by @sabine
  • (doc) Remove Unfold an Option section by @cuihtlauac
  • (doc) Minor line editing for Labelled Arguments by @christinerose
  • Issue Use "parameter" and "argument" appropriately has been resolved by multiple PRs from @PoorlyDefinedBehaviour
  • Fix link in 'Other installation methods' collapsible by @norskeld
  • (doc) Updated "Operators," adding a link to the operator table in the language manual by @cuihtlauac
  • Use a filename different from the library name in Your First OCaml Program by @cuihtlauac
  • Mention labelled parameters in A Tour of OCaml by @PoorlyDefinedBehaviour
  • Mention labelled parameters in Values and Functions by @PoorlyDefinedBehaviour
  • (doc) add more info about multiple files by @heathhenley
  • Include text on if-then-else and begin-end by @cuihtlauac
  • Fix a typo in programming guidelines by @presenthee
  • Fixing #1979 Link on privacy policy page 404 by @The-Amoghavarsha
  • Fix typo in the tutorial on optional params by @julbinb
  • (typo) Add missing space on packages page by @sabine
  • Improve documentation on Editor Support by @PizieDust

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:

• Learn/Get Started + Language + Guides by @oyenuga17
• Learn/Excercises by @oyenuga17
• Learn/Books by @oyenuga17
• Learn/Platform Tools by @oyenuga17
• Packages Search Results by @oyenuga17
• Packages + Community by @oyenuga17
• Blog + Jobs + Changelog by @oyenuga17
• Learn/Overview by @oyenuga17

General Improvements

Most Notable Changes TLDR:

• We merged a basic documentation search feature in order to search inside the OCaml documentation. It is available on the Learn area "Overview" page at https://ocaml.org/docs! There's room for improvements here, the most notable of which would be adding typo correction.
• 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:

• General:
  • Documentation Search Feature by @SaySayo and @sabine
  • (feat) add recommended_next_tutorials capability by @enoonan
  • Add precompile check for Recommended Next Tutorials by @enoonan
  • (feat) add prerequisite_tutorials capability by @PoorlyDefinedBehaviour
  • Add Package Versions Page by @sabine
  • Make changelog reachable from the landing page by @FatumaA
  • Fixing #1989 Misaligned select drop down on jobs page by @The-Amoghavarsha
  • Implement active state on exercise sidebar by @oyenuga17
  • Update Utils.human_date to use the newer Timedesc API by @darrenldl
  • Fix language manual banner HTML by @sabine
  • In case docs-data.ocaml.org is unreachable, fail more gracefully by @sabine
  • (bug) Fix String.sub exception if changelog length < 100 by @sabine
  • Gitignore *:OECustomProperty by @sabine
  • Remove The OCaml System from home by @cuihtlauac
  • Simplify typing of recommended next tutorials by @cuihtlauac
• Package documentation:
  • The docs-ci pipeline no longer pins odoc, allowing Voodoo to take control of its dependencies for better separation of concerns. by @sabine
  • Refactor: Improve naming of different index modules by @sabine
  • Bugfix: Read Library Names from Packages Correctly by @sabine
  • Bugfix: Move H1 Title Rendering to the Correct Location by @sabine
• Data parsing (ood-gen):
  • Report file name on YAML error by @cuihtlauac
  • Changelog: infer date from slug if not in metadata by @emillon
  • ood-gen: call crunch on each directory separately by @emillon
  • Tutorial titles only as metadata by @PoorlyDefinedBehaviour
• Data:
  • Add two individual blog post entries by @IdaraNabuk
  • Changelog for Dune 3.13.0 by @emillon
  • changelog: opam.2.2.0~beta1 by @kit-ty-kate
  • Add Laval University as an academic user of OCaml by @bktari
  • Add 2 XenServer jobs by @edwintorok
  • (data) Added priver.dev OCaml feed by @emilpriver
  • Add changelog for Dune 3.12.2 by @emillon
  • Use Yaml dashes for lists by @cuihtlauac
  • Add missing Platform changelogs by @tmattio
• Repository docs:
  • Fix broken links in CONTRIBUTING.md by @cuihtlauac
  • (doc) Mention in CONTRIBUTING.md how to add images by @sabine