OCaml.org Newsletter: February 2024

Community
1

Welcome to the February 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.
  • OCaml Cookbook: A prototype of an OCaml cookbook that provides short code examples that solve practical problems using packages from the OCaml ecosystem is on OCaml Cookbook.
  • Dark Mode: We’re almost ready to release dark mode now.
  • Community Section Rework: We are preparing wireframes for the community section to better present the existing content. In addition, we started preliminary work towards a dedicated “Events” page.
  • 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 & Outreachy Application Period

There are open issues for external contributors. However, since GitHub - ocaml/ocaml.org: The official OCaml website. participates in the Outreachy application period, we might have a shortage of open issues in March, since Outreachy applicants will quickly take them on.

You can find open issues for contributors here!

OCaml Documentation

User Testing

Twenty-one brave newbies accepted being observed for one hour while discovering OCaml through the online docs and completing a couple of programming tasks. Many thanks to all the participants of the user testing sessions we held!

Half of the user testing participants used the recently updated tutorials, the other half used v2.ocaml.org/docs. Our takeaway from this is:

  • Learning OCaml isn’t hard. However, learning functional programming is. Most participants who had previous FP experience successfully completed the tasks.
  • The updated docs do a little better than the manual at teaching both OCaml and FP to participants without FP experience. A few of them succeeded at the more complex tasks using the new tutorials, while all participants without FP experience failed using the old documentation.

By observing the participants try to make sense of the tasks and find relevant materials in the documentation, we have identified many smaller changes that are likely to improve the user experience on the documentation pages.

Relevant PRs and Activities:

Upcoming OCaml Cookbook

We made some progress towards adding a new, community-driven section to the Learn area: the OCaml Cookbook. The cookbook aims to be a compilation of recipes that provide code samples that solve practical-minded tasks using packages from the OCaml ecosystem.

Here is the design we are considering:

  • Category: High-level groups of tasks, e.g., networking, data compression, or command line arguments.
  • Task: Single thing to be done in a category, e.g., write to a file, make an HTTP GET request, or return an exit status.
  • Recipe: Version of task using a package, e.g., HTTP GET using curly or cohttp.

A rough prototype is on OCaml Cookbook. The contributions and the user feedback we received suggest that the structure of the cookbook needs to be refined one more time until it is ready to be released.

A good place to give feedback on the cookbook is this discuss thread.

Relevant PRs and Activities:

Dark Mode

In December, oyenuga17 started to implement the new dark mode on OCaml.org.

By now, the new dark mode is mostly complete, but it hasn’t been reviewed or tested sufficiently.

We have enabled the dark mode on staging.ocaml.org, based on your browser / operating system preferences. If you want to help, you can view the dark mode on staging.ocaml.org and report anything you see by opening an issue.

Completed Pages:

Community Section Rework

This month, we have started to do user research on the community area and gathered feedback and ideas on the current pages. Among others, we have identified these:

  • the Community section needs a better Events directory
  • the Jobs page needs to be more easily reachable from the community page
  • it would be great to highlight Open Source projects from the OCaml ecosystem that are looking for contributors

If you have opinions on the community section, feel free to share them in this discuss thread!

Relevant PRs and Activities:

General Improvements

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

Relevant PRs and Activities:

10 Likes