Looking for Participants for User Survey on ocaml.org Package Documentation and Learn Area

Community
,
1

Hi all,

the ocaml.org maintenance team is working diligently to bring you desperately needed UI/UX improvements. Starting right now, we are working with a UI/UX designer (hi Claire!) to make sure that the changes we make improve your experience on the site while also looking nice!

We’re running a (short) user survey via Google forms on the package documentation and learn areas with two goals:

  1. to get a broad overview of what the most pressing UI/UX issues to fix are, and
  2. to recruit some participants for interviewing them in a 20 minute video chat with Claire (optional)

To participate, please fill out the survey at OCaml.org Learn and Package Documentation Survey (any feedback is useful, you do not need to be available for interview to participate)

Claire is an experienced UI/UX designer, but not a developer, so having the opportunity to get to know the community while also learning what problems you are experiencing on ocaml.org is very useful to bring her up to speed.

It is likely that there will not be enough time to interview everyone who offers to help, but if you get invited to an interview with Claire, do not hesitate to show her what is, according to your experiences, wrong or broken with the package documentation and learn area on ocaml.org.

10 Likes
2

Hi, a quick question, the first question in this survey is:

Are you using OCaml for business or personal use?

Business

Personal

  • If I use it for research purposes, what do you want me to select?
  • and if I use it both for hobby projects and professional projects ?
1 Like
3

Fixed, ty for mentioning. This slipped past us, but indeed, research and the possibility that someone is using OCaml for multiple purposes makes sense!

5

We could still use a few more people for Claire to interview or to give input on what you think is most urgent to fix. :slight_smile:

6

will we see the results of the survey once it’s over by the way?

7

I commit to posting a higher-level summary on January 20 in this thread, but not people’s individual answers. This is for privacy reasons (and so that you don’t hold back describing, even if it may personally identify you).

1 Like
8

Hello! Here’s my feedback :slight_smile:

I find this fixed orange tab quite irritating and distracting.

image
image309×505 28.6 KB

So much so that I took the trouble to create a little script on my iphone to remove it (a few weeks ago).

It’d be nice if you could find a way to make accessing the sub-menu items less “intrusive”. IMO putting everything into the hamburger menu would be fine and not surprising at all.

Great job overall :+1:

1 Like
9

If you allow me to repeat myself (I mentioned this a couple of times I think for various places of the documentation), here concerning the ‘playground’:

I still don’t understand why it is illustrated with this horrible implementation of Fibonacci.
If you use the proposed algorithm to compute for instance fib 50,
I think you can do the computation by hand (pen and paper) faster than the computer!

Whereas the “normal” recursive algorithm for Fibonacci gives the answer instantaneously.

This will potentially make people visiting this page think “Oh my, they don’t know what they’re talking about in this community” :frowning:

2 Likes
10

It looks like main page looks buggy when window size gets thinner

image
image889×1206 222 KB

1 Like
11

I don’t manage to keep up to date with all the discussions on here, so repetition is definitely welcome.

Do we have a better code example that shows off the new multicore support on OCaml 5? With issues like this one, I’d be super happy when someone opens an issue on GitHub - ocaml/ocaml.org: The official OCaml website. to propose a better code example. I can get these added and merged very quickly.

12

@benjamin-thomas I opened an issue here Make the the sidebar-opening handle less obstructing · Issue #818 · ocaml/ocaml.org · GitHub

@Kakadu I opened an issue here: Display of featured packages could look better on smaller screens · Issue #819 · ocaml/ocaml.org · GitHub

Thanks for showing how it’s broken or looks wrong! Feedback like this is good to work with. :slight_smile:

1 Like
13

I recently realized that Brave browser enables speed reader mode automatically for some pages. In this mode monospace font has two weird sizes. I’m not sure if original web-site can control it, but I wrote this down anyway

image
image1264×1160 109 KB

1 Like
14

I understand that (and why) everybody in the community is enthusiastic about multicore, but
it this clear that such a “playground” area should display this new feature?

Do you have an idea of who is using this page? My impression is that it was more targeted to beginners, and then more basic codes would be more appropriate (?)

15

Makes sense. There are better places to show off domains (with a more realistic example for their use, too), e.g. in a dedicated tutorial. :+1:

16

I find the Learn page particularly hard to navigate (Mozilla Firefox 91.13.0esr on Debian 11):

ocaml
ocaml2040×1943 278 KB

2 Likes
17

Specifically for multicore the spectral norm example is quite nice for benchmarking the basics of multicore, however it is a lot longer and not something to show as a beginner example:
https://v2.ocaml.org/releases/5.0/manual/parallelism.html#s:par_iterators

1 Like
18

Glad you found it useful :slight_smile:

Regarding the Fibonacci example, maybe just rename the function naive_fib and point to this URL in a comment just above the function name?

See: OPCEB chapter 8 on memoization for a more performant implementation

I think I may have another suggestion, I’ll detail a navigation experience from a user’s perspective.

Step 1: I go to the ocamlformat repo on github and see this mentioned on the README

For more information on configuration options, check out the documentation or run ocamlformat --help .

Step 2: Once I clicked on the documentation link, I’m greeted with a (mostly) blank page.

Step 3: A little surprised initially, I have to scan the page visually and carefully to see the documentation link on the right.

image
image1456×790 43.4 KB

The documentation is probably the most important information and should be displayed “front and center”

As a comparaison, here’s a screenshot for an Elixir package:

image
image1065×910 99.9 KB

There is no way you can miss that documentation link as your attention is naturally drawn to it reading top down, from the center of the page.

Also, thinking about it more, the center and largest portion of the page for a given package on ocaml.org being mostly blank gives an overall impression of “emptyness” on desktops. Perhaps that could be improved?

Here’s the link to the Elixir package page mentioned above, for inspiration. IMO whoever created those pages got many things right and their implementation could be used as a reference.

3 Likes
19

I find the Learn page particularly hard to navigate (Mozilla Firefox 91.13.0esr on Debian 11):

Thank you for including the browser version - this is quite different from what I see on all the browsers I have installed and clearly not what was intended here. Are there any nonstandard settings (e.g. font size) used?

I created an issue here Mobile/Tablet Layout is Rendered on Monitors With a High Pixel Density · Issue #822 · ocaml/ocaml.org · GitHub for the problem that your browser seems to display the tablet/mobile layout of the page, and Height of the Hero-Links on the Learn Page on md- and below screens · Issue #823 · ocaml/ocaml.org · GitHub for the way too tall hero links. (I remember @dbuenzli also reporting this height problem to me, but it fell off my plate. Good that we’re getting to it now.)

20

This is curious actually, because ocamlformat clearly has a nice readme that I would have expected to be reproduced on the package overview page (that the link goes to). Some package overview pages appear quite empty · Issue #825 · ocaml/ocaml.org · GitHub

Clearly, the intention of ocamlformat here is to link directly to the documentation. After we fix the URL structure to allow people to link to the latest version of the documentation of a package (https://github.com/ocaml/ocaml.org/pull/793), the link on the GitHub repository’s README can be updated to go directly to the documentation.

I also agree with you that the documentation link should be much more prominent in order to easily find and click it. Package Documentation Link should be more obvious and clickable · Issue #826 · ocaml/ocaml.org · GitHub