V3.ocaml.org: getting ready to launch

I like the clean look and general direction. But a few points about the first impression, which I think is important:

  • It’s good to show code to convey the flavour. But the code is exceedingly simple and these functions look simple in most languages. In particular, it does not show a type definition and or pattern matching over such a type, which is simpler in OCaml than in most languages.

  • A button About OCaml raises the question what I am looking at. I was expecting to find that question answered at that very page and not somewhere else. If this page is not about OCaml, what is it about?

  • The Get Started button would be better placed slightly lower - maybe after the code. It seems silly to want to start something without having read anything about it.

  • The endorsements by companies seem also not adding value in the place where they are. I’d find the endorsement more appropriate later - after I’ve seen the strength of the language.

Altogether I am not convinced of the way the story is told when I look at the first two screens. Most languages try to tell a similar story. Haskell, as a close relative, does a better job than OCaml v3 in my opinion.

5 Likes

The home page doesn’t render properly for me, I tried both Chrome and Firefox on Windows. It is wider than the screen so some elements get cut off, and there is no horizontal scrollbar.

For example, Dune button in the section “Strong community” is cut off on the left side. (I’m for some reason unable to upload a screenshot).

To add to what @lindig said, on /packages page there is big heading saying “Opam:…” but there is no link to give more details about opam and more importantly how to use it.

Also, I think it would nice if one could browse all packages like it is possible on opam.ocaml.org now. (by date or alphabetically)

awesome that it has (almost) no 3rd party stuff. :heart:

what is unpkg needed for?

out of curiosity – I see quite some yaml at v3.ocaml.org-server/data at main · ocaml/v3.ocaml.org-server · GitHub but few s-expression. How comes?

1 Like

Thanks once again for the constructive feedback everyone. I don’t disagree with anything I think, I thought I would just try to answer some of the questions (or point various things out).

Agreed, multiple people have said this. It indicates the state of the package’s documentation. Green means it built fine and so it can be browsed. Orange means it still needs to be or is currently being built and red means it failed to build (e.g. luv 0.5.10 · OCaml Package). I’m not sure how to show these various states?

Thanks! I don’t think there’s much to add beyond @avsm’s original comment:

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…

Yep, agreed. If you have an idea for a good, short code-block feel free to suggest something: Good code example for the homepage · Issue #233 · ocaml/v3.ocaml.org-server · GitHub

Yep, there’s an issue for that thanks :)) Packages in "Strong Community" section scroll off screen · Issue #237 · ocaml/v3.ocaml.org-server · GitHub

Adding that explicitly would be good with those search features. You can get the whole list be searching for “nothing” but that’s not intuitive :sweat_smile: OCaml Packages · Search Result

This in combination with the comment about increasing the information density sounds good to me :+1:

Thanks for pointing this out. It’s probably this v3.ocaml.org-server/layout.eml at 6bc9dce632bca5e210d941a742d72a25c52c2964 · ocaml/v3.ocaml.org-server · GitHub ? We could vendor that JavaScript like we do for all the other js libraries at the moment: Vendor swiper js · Issue #260 · ocaml/v3.ocaml.org-server · GitHub

We use the “jekyll front matter” format which I think is pretty common (at least compared to s-expressions) which means it integrates nicely with content managements systems (CMS) and non-technical folk might be able to read/edit it more easily. At one point we hoped to run something like Netlify CMS to ease the contribution of data to the site, and I think we would still like to. We just ran into permission issues with how Github authentication worked that shelved this for now.

3 Likes

At the risk of turning this into a bikeshedding topic, I’d suggest not showing anything when everything is fine. No reason to bring attention to it if there’s nothing to bring attention to.

For the other states you could use some “in progress” icon if it’s being built and a warning icon if it failed. But more importantly I think is that the tab should be in a disabled state in both cases, and that the icons, or the tab as a whole, should have a tooltip with explanation. Ideally the tooltip would also be shown when the (disabled) tab is clicked, so that it also works on touch interfaces.

4 Likes

that’s often claimed and rarely put to the test. But I understand yaml is much more fashionable at the moment. Complexity is a nightmare, however.

Thank you everyone for the amazing feedback!

I’ve been slower than I’d like to follow up, but we have been aggregating all the community feedback we received here, on GitHub and other places.

Here’s a list that summarizes every issue we are going to address to improve the experience base on the feedback we’ve received:

Before Launch

  • The Standard Library API is not easily discoverible

  • BUG - The tags in package overview should link to a search page

  • BUG - The package authors in package overview should link to a search page

  • BUG - Swiper is not vendored

  • Button to edit a documentation page

  • Implement a syndicated RSS feed for the OCaml Blog

  • Missing links to the mailing lists in community

  • Move community links to the top

  • Rename Discuss to something more general (e.g. forums) in community

  • The strong community section on the homepage is broken on mobile

  • The package search page is too dense

  • “OCaml” should be more visible on the homepage

Note: we’ve already sent PRs for some of these: https://github.com/ocaml/v3.ocaml.org-server/pulls

After Launch

  • Navigate to the source page documentation

  • Search through the documentation

  • Package search should be sorted by popularity and displays the usage number

  • The problem page should keep the statement when displaying the solution

To Discuss

  • Consider removing the logos from the homepage, or moving them down

  • Option to override the README in the documentation

  • Document other build systems (nix, Bazel, etc.)

  • The featured papers are not relevant

  • The documentation status indicator is confusing


What seems to be the most urgent here is the difficulty to discover the Standard Library documentation, and the OCaml Manual.

As Anil mentioned, the OCaml Manual and OCaml API are not integrated into the site at the moment, and they still use the previous design.

Integrating them in the site is on our roadmap, and when this happens we’ll make sure that they are easy to find, and easy to navigate.

In the meantime though, we’ve opened a PR here to improve the discoverability: https://github.com/ocaml/v3.ocaml.org-server/pull/259

Don’t hesitate to chime in to give additional feedback.

For the feedback that we’re planning on addressing after launch (most of these are long-term projects, for instance, the documentation search), or that need more discussion, we’ll create GitHub issues so we can discuss specific features/changes there.

I’d also like to announce that we have a tentative launch date next Thursday. Until then, we’ll be preparing for launch by fixing the known issues (https://github.com/ocaml/v3.ocaml.org-server/milestone/2), and working on the feedback above.

Once we’ve launched, we’ll organize a community AMA session as Anil mentioned, I’ll post here when we have a date for it!

Thanks again for all the feedback. I’m very happy that the new website seems to be welcomed by the community, and to see so much engagement to improve it!

Multicore is coming soon, and the website is an important part of the signal we’ll be sending to newcomers and enthusiasts, so all your help and suggestions are appreciated :slight_smile:

13 Likes

Some first impressions:

The “Try” thing on the front page didn’t work for me, using Debian’s Firefox (78.15.0esr). It shows “Compiled with Js_of_ocaml version 4.0.0” but just ignores whatever you type. There are three hollow coloured circles at the top-left, but none does anything. However, I tried it with Firefox 96 in a VM and that worked (except for the circles - are these supposed to be macos window controls?).

The page width calculation seems wrong. It seems to be in mobile-mode on my desktop, with a single column and loads of white space. The “Strong Community” section goes off the sides of the screen. Both of these problems are also fixed by using a newer Firefox, though.

The main page has a picture of a man, a pot plant and a padlock next to “Fast Compiler and Efficient Applications”. I can’t work out what the connection is. Maybe remove the picture?

There doesn’t seem to be any way to stop the auto-play animation in the editor section. You can drag it, but it just starts up again. This makes it difficult both to read the text next to it, and to examine the image.

The site is unusable if you turn off styles (View → Page Style → No Style). Just a long list of gigantic icons. It is fairly usable in w3m, though, but the “Learn more” buttons (e.g. under “For Industrial Users”) don’t work.

The doc site is totally unusable for me on my laptop (13’’). Just for comparison below is a screenshot of the same doc page rendered by odig and on v3.

A few comments:

  1. Some documentation is lost.
  2. The page toc (“On this page”) is unavailable and lost. In general “In this package” (available via the right arrow on v3) is much less important than “on this page” which has the page’s signposts.
  3. The flush-right breadcrumbs to navigate the module hierarchy is totally unusable (clicking on it is spatially unpredictable).
  4. In general put emphasis on showing the documentation CONTENT not the package bureaucracy and the website chrome. You are using half of the page before the page fold for chrome, white space and dubious information. Do I really need to see brr's tag line on each of brr’s documentation web page ? Likely not. Do I really need such a large version switcher ? Likely not. Do I really need these huge switching tabs ? Likely not. Do I really need to stare that much white space ? Likely not.

The site may “look good” but the HCI…


3 Likes

Thanks for the great feedback, me and my team worked on the site, and all of this is great feedback. The images aren’t finalised so those would be updated.

With regards to the page width calculation, can you share a screenshot of why the site looks like to be mobile mode to you on your desktop, so I can diagnose the problem better.

Thanks for the great feedback, me and my team were responsible for this site, and based on a comparison with just a documentation site, the site definitely can be improved and more real estate can be given to the actual content. The rendered by odig variation you pointed out is a prime example of that.
Obviously I lose the page links, the overview, the version switcher etc, but as you mentioned, that is not relevant for someone reading the doc.

If we go with an approach like that, we will lose how the page is connected to the site in general, but I’ll see if we can come up with a compromise, or even an easy “reading” mode or something that does all that for you.

PS: We were only responsible for the UX/frontend, not things that are actually missing in terms of content.

Here’s the top of the main page. The menu bar has been compressed into a hamburger menu, even though there’s loads of space, and there’s only one column. Most of the page is the interpreter (which doesn’t work):

In the Strong Community section, only a few boxes are visible (and the page can’t be scrolled horizontally):

For comparison, here’s the old site, with a menu bar, search, links, news, RSS feed link, an example of some OCaml code, and a (rather out-dated) list of new packages, all on one screen:

1 Like

Thanks Talex, we’ll have a look at this!

Thanks for the feedback @dbuenzli and @talex5!

The launch is the first step, but of course, the effort to improve the experience on the site won’t stop there, and we will loop back on the design and UX of each page to iteratively improve it.
In particular, I agree that we can do a better job with mobile viewports and the use of spacing in the package documentation.

Speaking of launch, we have a new tentative launch date next Tuesday - stay tuned :slight_smile:

We should have addressed most of the issues listed as blockers for the launch in my previous post (and opened issues on GitHub to track the others), but please keep the feedback coming and we’ll try and address anything that looks like it should block the launch or that we can squeeze in if it’s a small fix!

One thing unrelated to the feedback: I’ve spent quite some time looking for OCaml job opportunities in the community and aggregated everything I found in the job board.

Hiring OCaml developers and finding OCaml positions was a pain point that stood out from the latest OCaml survey. The job board is a good framework to address that, but we’ll need as many listings as possible to incentivize more companies to share their job posts, and for candidates to look at the job board to find new opportunities.

If you are hiring OCaml developers, don’t hesitate to add your job post here: https://github.com/ocaml/v3.ocaml.org-server/blob/main/data/jobs.yml

5 Likes

What is the y axis unit in this graph? Is it seconds?

2 Likes

That’s in seconds, yes :slight_smile:
The data is coming from OCaml Benchmarks

I found the graph a little hard to grok at first. Perhaps it would be clearer for the graph to show kloc/second/core. Another nice thing you could do is include benchmarks for both native-code and byte-code compilation, to support the observation that the byte-code compiler is faster.

It’s tricky, but it would be neat to have some comparative data. If OCaml runs at something like 2-8k loc, how fast do other languages (C, C++, Java, Rust, Haskell) run at? Are there any experiments about this we can point at?

y

2 Likes

The book “OCaml from the very beginning” by John Withington has been released free of charge, thanks to support by the OCaml Software Foundation. It seems to me that it would merit being prominently displayed in the new site (maybe even in the landing page?) as a quality source of information for beginners.

Cheers,
Nicolas

10 Likes