V3.ocaml.org: getting ready to launch

Community
, , , ,
21

Overall: love the new page, it’s a great improvement over the old one. Very nice design and great work!

What follows are some suggestions/ideas from the point of view of trying to improve adoption of the language across the industry.

–

The events section threw me off at first because it prominently featured two workshop from 2021 that already passed. But when I clicked in there, I saw that there are videos on all presentations, which made me happy to see.

Obviously, if there’s an upcoming workshop, that one should be prominently visible.
Maybe we can emphasize that there are video recordings of past workshops available?
Or maybe it makes sense to show the meetups right on the Community page at OCaml Community?

–

The wording “Still here? Try some of our social channels for more information about us” on the community page is not particularly strong. When people really are still here, it might be because they’re looking to get help with their questions about the language, or they might just be looking for someone to talk to about their ideas and projects. So that’s where we use the trigger words that remind people of the reason why they’re here and which platform is the most appropriate for their need.

The people who interact (and grow the community) are not looking for “information about us”, and they’re not looking for channels that feed them something, but they’re looking to solve a problem they have.
Some people have questions that need answering.
Some people browsing the community page are business owners investigating whether OCaml is the language they should adopt - they’re looking for an active and lively community for their employees to participate in (e.g. activity on StackOverflow), they’re looking for discussions on the advantages and disadvantages of the language, and how to solve their problems with OCaml. They want to know whether there’s a supply of qualified people they can hire, or how fast a new hire can get up to speed using the language productively.

What the wording should do is give people who are on the edge of creating and sharing content and participating in discussions that tiny push that makes them sign up and go in and enjoy being a part of the community.

Possible replacement for the copy:
“Join our communities!”
“Ask and answer questions, share and discuss OCaml-related articles and posts, let people know about your projects and find collaborators”

Reddit - “join the OCaml subreddit and posts discussions and memes, talk about your projects, and share interesting articles and news from the web”

Does that make sense? I think a bunch of the other copy could be improved by making it more specific / call-to-action-y too, but I don’t have a lot of ideas right now.

–

“Curated Resources” on the main page conceptually belongs with the “Learn” part of the page hierarchy.

The copy “Here are some of the reasons why you should use OCaml for your workspace or institution.” doesn’t make sense. These resources are not the reason why people should use OCaml, but they enable them to pick up OCaml real quick and get to building amazing things with OCaml.

Possible replacement: “Get up to speed quickly to enjoy the benefits of the OCaml programming language across your projects”

I am not sure if Curated Resources should be on the main page at all. Maybe a simple “Get started” block on the main page, one that advertises getting up to speed quickly and how many resources there are, would be better. This one could link to the “Learn” page.

–

My impression is that the Success Stories deserve a place in the spotlight more than the lists of industrial and academic users, or the curated resources on the front page. Yes, we should be linking to these lists as they are impressive social/industrial proof that the language is established, but what’s really more fun and interesting to read is the success stories. So, I would reduce the size of the “For Educators” and “For Industrial Users” boxes and feature the success stories below that.

6 Likes
22

Nix is actively used by OCaml users, but it’s not a build system, it’s a package manager. I.e., it’s not an alternative to Dune, it’s an alternative to opam.

23

FYI

The “Documentation” tab link on these pages:

goes through to a 404 error:
https://v3.ocaml.org/p/ocaml/4.14.0/doc/index.html

24

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
25

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).

26

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)

27

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

what is unpkg needed for?

28

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
29

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. https://v3.ocaml.org/p/luv/0.5.10). 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 playground · Issue #233 · ocaml/ocaml.org · GitHub

Yep, there’s an issue for that thanks :)) Packages in "Strong Community" section scroll off screen · Issue #237 · ocaml/ocaml.org · 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: https://v3.ocaml.org/packages/search?q=

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 ocaml.org/src/ocamlorg_frontend/layouts/layout.eml at 6bc9dce632bca5e210d941a742d72a25c52c2964 · ocaml/ocaml.org · GitHub ? We could vendor that JavaScript like we do for all the other js libraries at the moment: Vendor swiper js · Issue #260 · ocaml/ocaml.org · 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
30

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
31

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.

32

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
33

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.

34

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…

odig
odig2058×1974 444 KB

v3
v32058×1974 443 KB

3 Likes
35

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.

36

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.

37

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):

v3-1
v3-11900×1911 131 KB

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

v3-2
v3-21898×1908 373 KB

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:

old
old1900×1911 490 KB

1 Like
38

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

40

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
41

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

image
image2538×878 291 KB

2 Likes