OCaml Workflows

[patricoferris]

Explore OCaml

Current Work

Hi everyone, I'm Patrick working at Tarides on a project called "Explore OCaml". The purpose of Explore is to provide an as-up-to-date as possible set workflows for being productive in OCaml. Primarily this is done utilising the OCaml Platform that @avsm talked about at the OCaml Workshop as well as some battle-tested community libraries.

Please note the site is very much a work in progress.

• Explore OCaml made to look like ocaml.org: https://deploy-preview-27--ocaml-explore.netlify.app/

• Explore OCaml as is: https://ocaml-explore.netlify.app/

• Source Code: https://github.com/ocaml-explore/explore

  Some workflow examples include:

• Configuring editors (VS Code, vim, emacs)

• Fixing bugs in third party packages

• Adding units tests and setting up continuous integration

• Publishing and releasing to Opam (not written yet...)

• Profiling OCaml code

There are quite a few great resources (like blog posts) on how to do specific things, but no centralised recommend way to do them. My OCaml journey started more or less a year ago (along with some others) and we all seemed to share the same pain points around documentation of tooling and workflows. Fundamentally this builds on what @johnwhitington described in #1136 but focusing on the OCaml Platform.

Proposal

Do people feel this kind of content would work well on ocaml.org say under explore.ocaml.org or similar? What's important is that there is a strong focus on getting a fairly specific task done. The dune documentation is great, but for many it is not immediately useful when they have the question "how do I start a new OCaml project" or when they find a bug in someone else's code the opam source and opam pin tools won't necessarily spring to mind from the opam documentation.

This is fine, those documents are not there to catch these cases, but I believe something like Explore OCaml could. I think this will also help unify and solidify the OCaml Platform as a community-approved suite of tools for achieving these workflows.

Lessons learned from building Explore OCaml

Whilst building Explore OCaml, I think I've come across a few key aspects that are (in my eyes) crucial to a site whose primary purpose is to inform and document. Perhaps some of these lessons are transferrable to OCaml.org.

• Meta-data is key: what I mean by this are things like timestamps for when workflows/tutorials were last updated or what versions of the tools were used to achieve a workflow/tutorial. Integrating this as a fully supported feature helps many people accessing the site understand immediately how current the information is. It also makes it easier in the long run to triage data for example the workflows available to application developers.
• Continuous Integration is important: the Explore OCaml (to the best of my abilities) has many example folders which on every PR are built when dune build and dune runtest are executed. This is a big maintenance burden lifted off the maintainers as the content is continuously tested (and could be on multiple OSes) to ensure it is correct. Mdx ensures the inline code is also correct using the dune diffing functionality.
• Easing the burden on developers: making the site well documented and providing tools to build it can greatly increase the likelihood of contributions. In Explore OCaml there is a CLI tool (explore) for building the site, running a local development server (which rebuilds on refreshes making it easy to preview changes), a "wizard" for generating new content types and linting those files to ensure they are correct. It acts as a mediator between developers that want to contribute and the maintenance and sustainability of the site.
• PR previews: again from a maintenance point-of-view the PR previews make it much easier for developers to review PRs, Explore uses Netlify but there's no reason there couldn't be a self-hosted solution.
• Accessibility is important: I've been trying to make an effort at thinking of solutions for ensuring good accessibility standards. One such effort is an automatic check (in code) that headers are properly nested. Another is using tools like Google's Lighthouse to catch other common problems (for example the colour for links on ocaml.org is flagged as not having a good enough contrast ratio).
• Using standard methods: OCaml isn't necessarily the first PL that springs to mind when building a site, but keeping everything written in OCaml lets you focus more on the content because everything stays in the same ecosystem. That being said, I opted to use the jekyll formatting with YAML front-matter because people familiar with jekyll will know it, or other industry standards like GatsbyJS -- I think this is helpful for people who want to contribute with content without having to learn a new (or home-grown) formatting style or build system.

I think these points really help to maintain the code sustainably by trying to automate as many tasks as possible and offer a friendlier interface for people to contribute.

Lastly (thank you if you made it to the end) I would like to say thank you to the contributors and maintainers of ocaml.org -- I think documentation/teaching/informing is an often overlooked aspect to languages but one of the most important!

[avsm]

Many thanks for your work on this Patrick, and for posting the summary here. I'm working on making the ocaml.org site infrastructure be easier to contribute to (see https://github.com/ocaml/ocaml.org/issues/1178), and so I suggest:

• making a separate version of your site for now to demonstrate the workflows and utility, and get community feedback on them
• when the various pieces in https://github.com/ocaml/ocaml.org/issues/1178 settle down, we can investigate integrating your mdx/dune build directly into ocaml.org. It's a little complex right now due to the use of an alternative toplevel, but there's nothing that can't be fixed with a little autumn cleaning :-)

[patricoferris]

Thanks @avsm, sounds like a plan 🍂 🧹 !

If anyone comes across this issue then do feel free to head over to Explore OCaml and contribute whether that's fixing typos, imparting valuable workflow information or otherwise:

• Contributing Guide (for completely new people): https://github.com/ocaml-explore/explore/blob/trunk/CONTRIBUTING.md
• Workflows: https://github.com/ocaml-explore/explore/tree/trunk/content/workflows

[ghost]

I would add a link to explore in the header of awesome-ocaml and the homepage of ocamlverse, to help beginners now, until this content gets into ocaml.org proper

[patricoferris]

Good idea @kanishka-work -- it might also be useful to publicise more generally (as WIP) given the recent results of the OCaml survey where documentation/opam+dune/workflows featured quite heavily imo.