v3.OCaml.org: A roadmap for OCaml's online presence

As a part of the team that started thinking about v3.ocaml.org back in Autumn 2020, it is incredibly rewarding and encouraging to see such a positive response and constructive feedback to the new, work-in-progress version of the site. A lot of deliberation and effort has gone into what we currently have and now that is publicly available, hopefully will gain community support and momentum to improve it further. I thought I’d answer some of the questions people have here.

Indeed. Much like the OCaml compiler itself, the “main” ocaml.org website has a commitment to backwards compatibility as well as new content and features. What I mean by this is we are trying to incorporate everything in GitHub - ocaml/ocaml.org: The official OCaml website. as well as creating new content/features. This inevitably makes things a little slower, but best practices are in the works.

Afaik opam already has tags they are just not used that widely or in a standardised way for indicating things like graphics, databases etc. (in fact the server reads them). If some consensus was reached on this it should be a fairly straightforward and useful feature to add. In the meantime we could certainly add curated lists of packages to ood :)).

When making the technology choices, the main reasoning was “use the right tool for the job”. In my opinion (as an avid jsoo user) for what we wanted jsoo makes little sense. The Rescript frontend is essentially bindings to Nextjs (plus any other libraries from the JS universe that are needed). Rescript has good JSX support, integrates well with the npm world, has (arguably…) better FFI support with JS etc. When we need jsoo (e.g. the experimental plan to have integrated toplevels for packages) then we’ll reach for it.

That’s not to say you can’t use jsoo for front-end work, for example there are bindings to reactjs and FRP libraries like brr + note. Another very flexible way for building static sites with a sprinkling of JS when needed is using OCaml for HTML generation and alpine.js for bits of javascript (e.g. the preview app in ood).

Importantly, now that the data lives very much separately we’re also not tied to any particular front-end. In fact this allows us to share all of the data in ocaml.org (I think there’s more than people realise, that was certainly the case for me!) for example I wrote an in-complete “terminal rendering” of the data. Ood could equally be reused perhaps directly in vscode!

8 Likes

Enjoying the new design direction.

Big win here too is the use of modern and community-built tools like Dream and Rescript. It sets a great precedence of what and how a modern system can look. Makes OCaml feel very possible for those interested in adopting this stack.

7 Likes

This looks awesome and is definitely going to push the community and ecosystem forward! I’m so happy to see centralized documentation as a thing that’s doable now.

2 Likes

I also hope that OCaml organization will participate into the Google Summer of Code 2022, like other languages, e.g. Haskell or Julia, do. It will help to find more potential young contributors, moreover, will attract more attention to the OCaml ecosystem and the current roadmap. Apart from that, it will require dedicated GSoC pages about the program, potential ideas for the tasks. Furthermore, some organizations have a good policy of having some “good first issues” that should be solved by the students to apply for the GSoC. This might need a separate page as well.

Why I am writing this? It will need to be on the site as well, assuming OCaml will apply for the GSoC 2022.

See also Google Summer of Code and GSoC project on Coccinelle

2 Likes

The hardest question to answer is: should the site be a classic html site with very minimal interactivity, or should it be a richly interactive site? At first glance, one doesn’t really have uses for the interactivity, but then interesting possibilities start to creep in - an interactive map, interactive highlighting of table of contents position, a carousel to browse books. We’ll see if more desire for interactive features emerge, possibly when the manual starts to be integrated into the site.

If interactivity isn’t important, that leads to a wide path of technical options. If interactivity is important, the path gets narrower, but there are still a few interesting options.

1 Like

Not having spent so much time as part of the OCaml community, while reading people’s response regarding the topic in question, I can fairly judge that this is a better progress for OCaml at large. From own perspective, I’m confident to say that the new site and the incorporated features is so awesome. Thanks to the community’s support and efforts.

4 Likes

Many thanks for all the constructive comments and suggestions so far, and also for those who have gotten in touch to contribute. Please do keep them coming (either on this thread or on the various issue trackers that @jonludlam and @patricoferris have pointed to). I’ll answer some earlier questions here:

The styling of the /packages sub-URL does indeed differ from the main design, but this is simply due to a temporary technical detail. The majority of the site uses React/NextJS to generate the frontend, and this uses the now-trendy medium-contrast colours and also features like fast-page-switching that NextJS offers. However, the documentation portion generated around 2.7 million individual pages when run across the full opam repository, and so we restored to dynamic generation of the content for that. What’s going to happen next is a rationalisation of the code across the ReScript and OCaml frontends so that there will be no observable difference in the colour schemes across the full site.

Regarding creating a categorised list of recommendations, that is absolutely in scope for the v3 iteration of the site. However, this metadata should ideally live in the opam-repository (for example, using tags as you suggest, which opam already supports). If anyone would like to have a go at this, I’d encourage PRs to the opam-repository to add the relevant tag metadata for a codex. Meanwhile, @lambda_foo @tmattio and @patricoferris are working on the core OCaml Platform workflow information for the guides section of the website which will cover opam, merlin, lsp-server, dune and so on.

Absolutely. The watch.ocaml.org has held up nicely after the OCaml Workshop, so I think it’s in good shape to populate with more videos. This needs a volunteer to help us upload the past nine years of videos from YouTube to watch.ocaml.org. If anyone wants to have a go, please message me and I’ll create you an account.

I’m not sure why you think the current ocaml.org new feed has been broken – it’s been working fairly reliably for the past decade. The only real problem came up a few times when a feed’s domain expired and got taken over by domain squatters, at which point we got spam into the main page of ocaml.org.

What I meant with that part of the announcement is that the syndication feed should not be mistaken with original news on the website. Right now it’s difficult to distinguish official announcements (such as compiler or opam releases) as they are a little scattered (e.g. on opam.ocaml.org). The plan is to combine the platform-blog with the new website directly. I’ve also been considering just having a special tag on this forum so that nice announcement posts could also be syndicated to the website easily (for example, @gasche’s compiler newsletters).

My general desire is to grow the planet feed and syndication system, but to clearly demarcate them as not being published by ocaml.org and to manage them via more modern decentralised techniques that feature spam, moderation and archival. PeerTube is a good example of this for videos that is working well, and I’d welcome suggestions for Atom/RSS (there must be something in this space, ideally ActivityPub-based).

Depending on how the experiments go, it’s very likely that we’ll have a Matrix homeserver for ocaml.org where CI bots can report status information (see this prototype PR) for ocaml-ci that will also apply to opam-repository. The goal here is to for ocaml.org to publish its data using an open protocol, which can then be syndicated into whatever technologies are in vogue (e.g. Discord, Slack, Teams, …).

So if you spot some decentralised syndication system that you think might be interesting for OCaml, please do let me know. Even better, if you’d like to develop one to tailor it to our needs, let me know even sooner :wink:

8 Likes

Note that there’s already an OCaml channel (hosted on matrix.org but anyone can join). :slight_smile:

1 Like

I guess everyone has it’s own notion of reliable but it does sometimes stop updating altogether (and that’s only the latest occurence).

If you have some funds to invest, get in touch :wink:

1 Like

Thanks for your work on this.

So that page uses various external resources: fonts, javascript, … – which allows these external partners to track (log analysis, cookies) clients.

For me, the most useful item on opam - Packages are the reverse dependencies – are there plans to add them to v3.ocaml.org/packages as well? That’d be highly appreciated.

2 Likes

Thanks for the feedback @hannes :))

That sounds like a good point. Do you have any suggestions or ideas for helping to improve this beyond minimising the dependencies? Perhaps an issue on v3 would be a better place to discuss that?

Yes! It’s on my todo list :))

This is an interesting point. So, two things:

  • These externally-loaded fonts can of course be made internally hosted, and the issue goes away
  • I checked and the page right now has no cookies (zero)

So, if you’ll forgive the pun, that tracks with what avsm said :slight_smile:

3 Likes

:raised_hand: send me some details of where I can get access to the originals too. I also want to try fixing the audio levels to remove the background noise, the older recordings are difficult to watch because of that.

3 Likes

There is a PR to add leaflet, which will make some runtime fetches for tiles, but at least the tiles won’t be coming from Google Maps.

There aren’t any widgets embedding Twitter, Facebook, or other feeds, so I can’t think of any other javascript issues at the moment.

Wow the new website is AMAZING :star_struck:. Fantastic work by the team. Especially the integrated docs. They look way better than before, and secondly what an amazing effort to have all the docs in one place!

5 Likes

Just another note of thanks: the centralized documentation site is great. I usually have odig keep a local site for the libraries I use most frequently, but beyond that, dealing with hunting down online documentation sites their significant style variations (looking at you, lwt :wink:) was a frequent, but no longer!, minor irritant.

6 Likes

Very nice! Though, starting from v3.ocaml.org, I tried to find a link to videos. Maybe, I did not search hard enough? Eventually, I remembered the url: watch.ocaml.org. Maybe, adding a link to this awesome service in the community page would be nice?
Thanks for the amazing effort!

1 Like

I think someone already said this but I can’t remember when and where: The integrated doc generator systematically skips the first comment before a numbered section, in each mli file. This is bad because this is where you often find interesting general comment about the module.

This can be seen for instance with tsdl or bogue

If not already done, where should I report this?

I reported it here: Some more documentation regression · Issue #203 · ocaml/ocaml.org · GitHub

2 Likes

thanks for the report! is it indeed quite critical