V3.ocaml.org: getting ready to launch

[avsm]

In my previous post this summer about the upcoming revision of the website, I gave an overview of where we were headed and presented a roadmap for OCaml’s online presence.

Since August 2021, we’ve made considerable progress. We’re on track to launch the website in February 2022 (only a couple of months beyond my summer prediction!), and the roadmap after that is becoming clearer thanks to all your feedback.

You can see it live at https://v3.ocaml.org/, with the package search available at v3.ocaml.org/packages

Let’s dive into it!

Update

Until August 2021, we had been working on the foundations for v3: the user flows, sitemap, and the reusable infrastructure for the data used in ocaml.org. With all the infrastructure and data ready, our efforts since have been focused on completing the frontend.

One of the clearest priorities we had from community feedback was to ensure that the unified package documentation gets to the live site as soon as possible. The build process for this is not trivial, as it involves combining the outputs of 20,000+ opam packages with the rest of the website, while maintaining a reasonable developer experience for the main site. We have therefore merged the various frontend and backend codebases into a single OCaml-based one. We’ve merged the NextJS / ReScript / Tailwind codebase to the backend server that serves the package documentation. This has allowed us to consolidate our technology stack and simplify our continuous deployment story, but also to directly serve the website from a pure OCaml stack (using packages from our own community such as Dream and ocaml-tls). We’re deeply grateful to the ReScript team for the technology that let us prototype the new revision of the website so quickly, and to implement the templates we’re now using.

Here’s an overview of the sitemap and all the pages we’ve implemented.

• Homepage
  • About
  • Industrial users
  • Academic users
  • Success stories
  • Success story
• Learn
  • Books
  • Releases
  • Release
  • Papers
  • Tutorial
  • Best practices
  • Problems
  • Manual
• Packages
  • Packages search
  • Package
  • Package documentation
• Community
  • Events
  • Workshop
  • Opportunities
  • Opportunity
• Blog
• Legal
  • Carbon footprint

In addition to the frontend work, here are some backend highlights:

• A global navigation bar on the package documentaion. You can now navigate through all package libraries from the navbar (by @TheLortex in #86)
• A toplevel on the homepage (by @tmattio, @patricoferris and @jonludlam in #106, #135 and #159)
• Added redirections from current ocaml.org URLs
• An internationalisation framework that serves pages in different languages. The framework exists, but the page translations will come later (by @tmattio in #84)
• A code-highlighting library that adds code highlighting in the tutorials (by @patricofferis in #108)
• Handled Let’s Encrypt certificate renewals and HTTPS redirects (by @tmattio and @patricofferis in #182)

See the full changelog here: https://github.com/ocaml/v3.ocaml.org-server/blob/main/CHANGES.md.

As mentioned above, we are feature complete, so we will be reviewing the site to get final approval from @xavierleroy and the core development team to launch the new site in a few weeks. We still have some work to do until then, but we’ll dedicate these next few weeks to receive community feedback and make any appropriate changes.

So now is the time to give us the feedback you have! You can do this by replying to this post or opening GitHub issues on the repository ocaml/v3.ocaml.org-server. Mostly, we’re hoping to receive actionable feedback such as:

• Are you able to find all the information you’re expecting to find on the website?
• Do you find the documentation (both the learn section and package documentation) usable?
• Do you find some design elements make the website hard to use (e.g., for color blind folks)?

Also, please don’t hesitate to open a GitHub Issue if you notice any bugs.

As you know, the release of OCaml 5.00.0, including Multicore support, is coming in 2022, so the timing of the v3 website launch is not coincidental. When OCaml 5.00.0 is released, the website will serve as an entry point for people new to OCaml, so we need to be ready with a usuable website, helpful documentation, clear package sites, etc. All your feedback and insights on how we can do better is greatly appreciated.

What’s Next?

Launching the website is the first step on our roadmap to improve OCaml’s online presence.

As mentioned above, the immediate goal is to be ready for this OCaml 5.00.0 release. With this in mind, for the next few months, we’ll focus on improving the documentation and ensuring it includes good user pathways to learn about Domains, Effects, and generally how to write concurrent programs in OCaml.

In addition to the documentation, some of the other projects on our roadmap are:

• An online editor integrated in ocaml.org (aka a Playground)
• Toplevels for all the packages that compile to JavaScript

This is an exciting time! Stay tuned!

How Can You help?

We need your help!

Until now, the development and design of the new site has been driven by a small team of people from Solvuu, OCaml Labs, Tarides, the University of Cambridge and individual contributors from our community. This was useful to get the momentum we needed to deliver on all the feedback from the community (package documentation, job board, new blog, etc.), but OCaml.org is a community project and needs to be driven by all of us.

In particular, we built what we hope is a good framework to represent the community with pages like:

• A job board
• The OCaml blog
• The meetings and workshops
• The industrial users and academic users
• The success stories

Now that the framework is there, we need your help to contribute to these pages, allowing us to serve great content and make the pages useful.

Job Board

The job board is an experiment. We’re hoping that we’ll get enough content on it so it’s useful for people looking for OCaml positions.

To do this, we need more job posts.

If you are hiring OCaml developers, you can add your job posts here: https://github.com/ocaml/v3.ocaml.org-server/blob/main/data/jobs.yml

Blog

The previous blog contained a lot of articles that had nothing to do with OCaml, as it was an unmonitored RSS/Atom aggregator.

A long term project is to build a decentralised RSS feed for the OCaml community to publish blog posts about OCaml. In the interim, we can keep using those RSS feeds but also list the article IDs we want to display.

If you have a blog about OCaml, you can add your RSS feed and list of articles here: https://github.com/ocaml/v3.ocaml.org-server/blob/main/data/rss-sources.yml

We would also like to integrate the Caml Weekly News (which recently celebrated its second decade!) directly onto the main ocaml.org website.

Events

At the moment, the Events pages lists the OCaml workshops and the Meetups.

If you’re organising events, don’t hesitate to put them here: https://github.com/ocaml/v3.ocaml.org-server/blob/main/data/meetups.yml

Perhaps we can advertise new events from the website, if that helps organising your events.

Success Stories

In the new website, we’ve revamped the success stories to contain detailed company descriptions and the way they use OCaml, including which challenges their business faced and how OCaml helped overcome them.

If you’re using OCaml, you can write a success story for your business here: https://github.com/ocaml/v3.ocaml.org-server/tree/main/data/success_stories/en

Tutorials and Manual

As mentioned above, we’ll be revamping the documentation in the next few months. This is a large project with a lot of content to write, so we’ll need the community’s help. If you’re interesting in contributing, don’t hesitate to reach out at thibaut@tarides.com to @tmattio.

The OCaml manual in particular is rendered using the old style, and we are planning to port it to odoc in order to fit in with the new style and also to cross-reference into the API documentation. (this requires more discussions with the core development team, and @octachron has begun looking at it).

Package Documentation

Now that we have a great package site with documentation, it’s time to write great documentation for your packages!

The odoc maintainers worked on some guidelines on how to write odoc files: odoc_for_authors (odoc.odoc_for_authors)

We’ll also be integrating toplevels for the packages you publish on Opam. It will use js_of_ocaml, so if you’ve published packages that should be compatible with js_of_ocaml, you can start making sure they are before we roll out the toplevels in the package documentation.

Acknowledgements

Thank you to everyone who contributed to the development of this new version of the website!

In particular:

• Ashish Agarwal (Solvuu)
• Kanishka Azimi (Solvuu)
• Richard Davison (Solvuu)
• Patrick Ferris (OCaml Labs)
• Gemma Gordon (OCaml Labs)
• Isabella Leandersson (OCaml Labs)
• Thibaut Mattio (Tarides)
• Anil Madhavapeddy (University of Cambridge)

For the groundwork on rethinking the sitemap, user flows, new content, design, and frontend and package docs!

• Jon Ludlam (OCaml Labs)
• Jules Aguillon (Tarides)
• Lucas Pluvinage (Tarides)

For the work on the package site infrastructure and UI!

• Paul-Elliot Anglès d’Auriac (Tarides)

For meticulously going through the website to find issues.

• Isabella Leandersson (OCaml Labs)
• Asaad Mahmood (Tarides)

For the work on the designs and bringing them to life on the frontend!

• Christine Rose (Tarides)
• Isabella Leandersson (OCaml Labs)

For the work on the new content and reviewing the existing one!

We’d also like to thank the major funders who supported work on revamping the website: grants from the Tezos Foundation and Jane Street facilitated the bulk of the work. Thank you, and if anyone else wishes to help support it on an ongoing basis then donations to the OCaml Software Foundation and grants to the maintenance teams mentioned above are always welcomed.

Moving forward, updates on the v3 website will be taken over by @tmattio, who has kindly volunteered to run a community video chat “AMA” about how you can get involved and contribute, and to give your feedback directly. He will post here with more details when timezones are all worked out. We would, of course, be delighted to also use other community channels / podcasts / Twitch / Discords / etc to reach out and get feedback and ideas.

On a personal note, it’s incredible to see this stream of hard work combine with the recent multicore OCaml merge to provide a modern, welcoming interface to the new users who will appear. I’m most excited about the future of OCaml we are embarking on with 5.0 – thank you to all who have been involved for being such wonderful collaborators.

[perry]

The new web site looks really amazing. Thanks are owed to everyone who worked on this.

[mro]

you scared the hell out of me placing that facebook logo jumping into my face.

[hongchangwu]

It looks amazing! Congratulations. I especially like the online REPL compiled with Js_of_ocaml.

Minor suggestion: can the link to the official manual be placed somewhere more prominent? I took me a while to find it.

[glennsl]

Looks really slick! The landing page in particular seems very well designed, and I love the package search and integrated package documentation. For my own use I do still have some complaints though:

• I no longer consider myself a beginner, so what I’m usually looking for is reference documentation. I think that’s a pretty common use case, possibly the most common, but still there is no mention of “documentation” anywhere on the landing page (other than a reference to package documentation). There’s also no site search to help me. After looking for a while, the closest I can find is “Learn”, so I click that. This page has what looks like a TOC in the column on the left, so I scan that for something like “Manual” or “API reference”. There’s nothing. I look to the right where I see three block things, one of which is titled “Language Manual” (yay!) but still no mention of any API reference. I click on the language manual block, and here I find another two-column layout with one kind of TOC on the left and another kind of TOC on the right. The TOC on the left has an item called “OCaml API”, which takes me to a listing of the available modules (yay!). Goal reached, but I had to go through four pages and a lot of scanning through those pages to get there, which I think is unnecessary for such a common use case.

• The API search is somewhat… peculiar. It’s for some reason case sensitive, and has some very distracting tooltip-like behavior on hover. But more importantly, there seems to be no way to interact with it outside the search input. To set it up as a search engine in the browser, for example, or to implement a url-driven shortcut like std.rs/<search term> that could redirect to an OCaml API search page. You have to actually go to the page, focus the search input and type something in order to initiate a search. I love that it’s possible to search for type signatures though!

• While the integrated package documentation is great, there seems to be no way to search through that documentation. Would be very useful for more complex packages.

• The package search, while comprehensive, offers very little in the way of aiding package selection. For example, a search for postgres yields 26 results, ordered more or less arbitrarily. How do I figure out which one of these I should use? It would have been nice if the results were ordered by some kind of popularity measure, for example, so that I could more easily pick the most likely candidates to evaluate first.

• I keep mistaking the “Get Started” button next to the package search field in the header for a search button.

[yawaramin]

Feedback from my end: the ‘edit this page’ (pencil icon) seems to have disappeared from the doc pages. E.g. I want to send a PR for Up and Running with OCaml · OCaml Tutorials , however I’m not sure how to get to the repo. I know I can find it but I have some experience with the OCaml repos. Many people might not. It’s a good idea to have ‘edit this page’ so people can quickly make suggestions.

EDIT: in case anyone is curious, my PR: Streamline opam package installs and REPL usage by yawaramin · Pull Request #1622 · ocaml/ocaml.org · GitHub

[anentropic]

I had similar thought to @glennsl - I would love to see an obvious “Documentation” link

At the moment it’s “Learn” → read the page, guess I want the “Language Manual” → yes this looks like the docs, how do I browse the stdlib? maybe “OCaml API” → then the page section “OCaml library” is the list of stdlib modules.

And the list of modules isn’t alphabetical, but nor is it organised into thematic groups (e.g. data structures, IO etc), seems just random.

So concrete suggestions would be:

• maybe rename “Language Manual” to “Documentation” as that’s what other langs call it
• link to it in the main menu of the website
• “OCaml API” is an obscure title for what it contains (I could imagine it was something about the cli tool, or FFI or something)
• maybe link directly to OCaml library : Stdlib instead, which contains details grouped into various logical topics, plus an alphabetical list of modules

[octachron]

The manual and the standard library documentation are a foreign import from the compiler’s documentation and manual. The lack of integration is thus partially on me. Hopefully, it should be improved once I have time to spend on the manual (generally during the beta phase of the release process).

It might be meaningful to keep the manual name to indicate that this is a separate source from the rest of the documentation.

[silene]

On the “Learn” page, there is this huge button “language manual” which I want to click on, but no, I have to click on the small button “take me there”. Similarly, I cannot click on the huge button “get started”, I have to click on “start now”. And the worst is the last one with its small button “I’m ready”. I suggest getting rid of the small buttons and just making the large ones actual buttons.

Still on the “Learn” page, I am really confused by the “Papers” section. The three papers I get shown (chosen randomly?) do not have anything to do with OCaml as it currently exists. If a user went to the “Learn” page, it is presumably not to learn about potential future extensions of the language. This “Papers” section has its place on the website, but not there at the top of the “Learn” page. It would be better to put the books there, for example, or some other online resources such as community blogs.

On the “Problems” page, it is a bit frustrating that it is impossible to see both the statement of the problem and the solution to it at the same time. Showing the solution should not hide the statement. Also, the lack of a clear visual distinction between what is input by the user and what is output by the interpreter will presumably confuse beginners. Finally, the page is overwhelming and it would be great if it could be split into several subpages. It does not even have to be split into meaningful categories. Just saying “problems 1-10” could make things more palatable.

[lambda_foo]

Perhaps this has been recently added but the Manual is available in the Curated Resources section.

@avsm Your link for news-sources is a 404 perhaps it should be v3.ocaml.org-server/rss-sources.yml at main · ocaml/v3.ocaml.org-server · GitHub from Integrate blog and news by tmattio · Pull Request #196 · ocaml/v3.ocaml.org-server · GitHub

[avsm]

@lambda_foo

Your link for news-sources is a 404

Good catch, now fixed. Thanks @lambda_foo!

Everyone, this feedback is just great! Please do keep it coming and get your opinions here. Rather than track individual issues, we’ll try to aggregate the feedback and apply it holistically so that there is consistency in the resulting site flow (an area where the existing v2 version could have done better on).

[fermin]

In the websites for other languages, the word “Haskell”, or “Rust”, or “Python” appears in a large font size on the top of the page. Can I suggest the same for ocaml.org? (In fact, right now the word “ocaml” appears in smaller font than the words “Bloomberg” or “Facebook” ! )

[lucas-deangelis]

Congratulations on all the work done, it looks great! A few remarks:

• As fermin said, having the word “OCaml” somewhere might be great. A quick example without styling is on the screenshot I put. Another option would be to use the logo on the footer that includes the “OCaml” word.

Unstyled text:

Using the footer logo, the alignment could be better but it was just a fast proof of concept:

• On the package search page (the one on the screenshot), I think the information density could be higher for the results. Right now I can have ~5 results by “screen”. We could reduce a bit the whitespace, and maybe put some info like the version and license on the right side. An example of a before and after:

Before, 959 pixels for ~5.5 results, so ~174 pixels for each results:

After, 679 pixels for ~5.5 results too, so ~125 pixels for each results:

I find the “after” worse from an appearance point of view, but better from a usability point of view.

There’s a small green dot that looks like a notification indicator to me but doesn’t disappear once I click the button. I find it a bit frustrating, and am not sure what it’s supposed to be.

Once again though, fantastic work and thanks to everyone that worked on this!

[nated]

On the Community page, it might make sense to move the links from “Still here?” (Discord, IRC, Reddit, etc.) above the “Recent News” and “Opportunities” sections - they’re perhaps a little more relevant on that page.

Also, maybe the “Go to Discuss forums” link should just read “Go to forums”? It reads a little awkward if you haven’t heard of Discuss the software.

Maybe it could be made more obvious that the code listing and “Try” button on the homepage is actually an inline REPL? As it is, it the design makes me think that “Try” is maybe either a link to a Playground-ish page, or a link to installation instructions. On Fennel’s homepage, for example, the text above the REPL is “you can use Fennel right here without installing anything”, and rather than a button to initialize the REPL, they just give you an input box straight away.

I love the papers page! There’s a bunch there I hadn’t read before, I hope it continues to expand in the future!

[pdonadeo]

A silly question: I’d like to update the rather outdated info on my company. Where I’m supposed to fill a PR? Is it ocaml/v3.ocaml.org-server, like @avsm suggested for the Job Board?

[patricoferris]

Not a silly question at all. There were multiple repositories before and now everything is consolidated into one, easier to manage and deploy repository ocaml/v3.ocaml.org-server. To update the company information it is most likely in one of these markdown files: v3.ocaml.org-server/data/industrial_users/en at main · ocaml/v3.ocaml.org-server · GitHub, thanks for wanting to update the information.

Also, thank you everyone for all of the constructive feedback! It’s great to hear the bits you do like as well as the bits to be improved :))

[lambda_foo]

Great work everyone the new site is fantastic.
Suggestions in no particular order:

• the results of a package search should be more compact and include extra metadata like last updated and usages. How do I find the popular Postgres bindings that are maintained?
• the tags on packages like graphql on dream 1.0.0~alpha2 · OCaml Package should link back to a list of similarly tagged packages.
• reverse index of author to packages, I can click on the author of a package but it goes back to the package page.
• the README and documentation tabs for packages is great, however there should be an option to override it when an author has put extra effort into building a standalone site. eg Dream — Tidy, feature-complete web framework
• How can people contribute to the COMMON TASKS section in Learn OCaml @tmattio ?
• Add nix and Bazel to the Other build systems section. If they’re actively being used?
• When browsing the docs for a package it would be great to navigate to the code for a function or module. I’m sure this isn’t an easy thing to do but I use it all the time in Haskell docs

That’s everything I have. Again super work I love the new site.

[Gopiandcode]

@lambda_foo

the results of a package search should be more compact and include extra metadata like last updated and usages. How do I find the popular Postgres bindings that are maintained?

This especially. I noticed a while back that Opam seems to have dropped usage information from the packages, and now even opam.ocaml.org doesn’t allow viewing the number of downloads of a package or sorting packages by usage, which is especially useful information when choosing packages to install. I’m not sure if keeping this metadata is difficult and that was why it was removed, but it was a particularly important feature.

With respect to the community section, it seems to be missing the discourse and mailing lists (I understand that the link at the top links to the discourse forum, I found it easy to miss).

There was an exchange on the mailing lists about how OCaml users with visual impairments often find mailing lists more accessible as compared to the discourse forums, so I guess the inclusion of a link to the mailing lists would be a good way to make the community more inclusive to developers with visual impairments.

[b0o]

Congratulations! I would be interested in hearing more about your decision to migrate away from ReScript.

[cloudyhug]

Hi. Great job, the website is gorgeous. I just have small suggestions for UI/UX improvement:

1. I expected the icons to be clickable.

Icons of sponsors could redirect to their official website, and the icons of IDEs to a GitHub page or the page of the concerned extension, according to the IDE.

2. The “Strong community” section has icons cut when they are on a side (Dune and Irmin). I am using Vivaldi.

Thanks to all the contributors.