Usability tweaks

[ludwigschubert]

Jochen & Co-authors, this is looking great!

Here's a small list of suggestions after which I'd suggest you could transfer the repository to the Github org distillpub where I'll ensure technical compatibility.

(E.g. We'll need to link against the most current version of the Distill template served by distill.pub. At the moment you may see math type out of place—this is a regression in newer versions of Chrome because the article is currently linking against an outdated build of the Distill template. In order to fix such bugs in the future without your input, we require linking against the hosted version of template. We also have our own webcomponents loader already built into the Distill template, and we need to create the meta tags programmatically to allow DOI uploading and other indexing. We'll also need to remove your Google Analytics snippet unfortunately. EDIT: I'll check about that with the other editors, actually. We haven't historically allowed this, but I wonder whether we have consciously thought about this. No guarantees, but I'll inquire. :-))

Suggestions

Make the draggable area of handles at least 44px big

At the moment it can be extremely hard to hit the handles on the Gaussian distribution diagrams. I'd suggest to do this with an invisible circle of radius 44px that intercepts mouse events the same way the current handles work. Please also set cursor: grab; on those elements to shwo they can be moved.

Maybe introduce Gaussian distribution parameters one-by-one

You already have a nice interactive diagram for a full Gaussian distribution. You could consider having the diagram be visible every time you introduce a parameter, with only that parameter changeable. So e.g. when you talk about "The diagonal of Σ consists of the variance \sigma_i^2σ of the ii -th random variable." it would be great to have the diagram with only the parameters on the diagonal adjustable.

This is just a suggestion to make the very introduction of Gaussian distributions more approachable. In our experience it is often valuable to focus on making the earliest sections of an explanation as accessible to readers as possible.

Add links to set state of figure #Posterior to its figcaption

In the (beautifully done!) figure #Posterior's figcaption you describe different states of the figure. It can help discoverability a lot to supply links on the relevant parts of the figcaption that on click call JS that sets the figure to the described state. Take a look (under) for an example of this behavior.

Clicking on the underlined text sets the position of the square in the above diagram to the described feature.

I'd recommend this approach for each of the italicized scenarios:

Without any activated training data, this figure shows the prior distribution of a Gaussian process with a RBF kernel. When hovering over the covariance matrix, the opacity of the gradient shows the influence of a function value on its neighbours. The distribution changes when we observe training data. Individual points can be activated by clicking on them. The Gaussian process is then constrained to make functions, that intersect these data points, more probable. The best explanation of the training data is given by the updated mean function.

(Please also remove at least the left margin of this figure so it aligns with the body text.)

[grtlr]

Make the draggable area of handles at least 44px big

At the moment it can be extremely hard to hit the handles on the Gaussian distribution diagrams. I'd suggest to do this with an invisible circle of radius 44px that intercepts mouse events the same way the current handles work. Please also set cursor: grab; on those elements to shwo they can be moved.

That makes a lot of sense - we have made the changes in PR #31.

[grtlr]

Add links to set state of figure #Posterior to its figcaption

In the (beautifully done!) figure #Posterior's figcaption you describe different states of the figure. It can help discoverability a lot to supply links on the relevant parts of the figcaption that on click call JS that sets the figure to the described state. Take a look (under) for an example of this behavior.

Clicking on the underlined text sets the position of the square in the above diagram to the described feature.

I'd recommend this approach for each of the italicized scenarios:

Without any activated training data, this figure shows the prior distribution of a Gaussian process with a RBF kernel. When hovering over the covariance matrix, the opacity of the gradient shows the influence of a function value on its neighbours. The distribution changes when we observe training data. Individual points can be activated by clicking on them. The Gaussian process is then constrained to make functions, that intersect these data points, more probable. The best explanation of the training data is given by the updated mean function.

(Please also remove at least the left margin of this figure so it aligns with the body text.)

We have added this functionality in PR #30.

[grtlr]

Maybe introduce Gaussian distribution parameters one-by-one

You already have a nice interactive diagram for a full Gaussian distribution. You could consider having the diagram be visible every time you introduce a parameter, with only that parameter changeable. So e.g. when you talk about "The diagonal of Σ consists of the variance \sigma_i^2σ of the ii -th random variable." it would be great to have the diagram with only the parameters on the diagonal adjustable.

This is just a suggestion to make the very introduction of Gaussian distributions more approachable. In our experience it is often valuable to focus on making the earliest sections of an explanation as accessible to readers as possible.

I am somewhat torn in between with this proposed change. On the one hand, I understand the advantages of the proposed approach from a didactic standpoint - this is also how I would introduce the covariance matrix in a talk or lecture. In an article like ours, however, I think that this approach also has some disadvantages:

• We would have three very similar figures, which might make it harder to identify the correct figure when the reader jumps back within the article.
• It might add some visual "clutter" as their would be only a sentence of text between each figure.
• All the required information already fits on one page, adding two more figures could scroll other related parts of the text (the equations, or definitions for example) out of the page.

@ludwigschubert Maybe it would suffice to mention the corresponding figure earlier, or even move it up within the article?

[ludwigschubert]

@grtlr I'm not confident enough in my opinion if you feel strongly, but let me attempt to outline a different view:

• You would not need to have three very similar figures—you could, for example in the default settings, highlight the different aspects the figure illuminates. Varying variance could start with one dimension having high variance, the other low, at zero covariance. Varying covariance could start with high covariance. (I stress this point so much because the current figure doesn't make it easy to adjust these numbers individually—dragging the handles performs the "intuitive" operation of stretching the distribution, but it doesn't highlight how the covariance matrix decomposes into standard deviations and covariance.)
• I agree that visual clutter can become a problem. It can help to ensure the figures are perfectly aligned. Repeating a figure can actually help identify visual clutter—for example I'd say the color legend next to the diagram doesn't actually provide important information. It can also help identify opportunities to highlight what did change: one could for example gray out inactive values in the covariance matrix, or consider labeling its entries
• There's no real concept of a page in web publications. I'd expect your article will be read on mobile phone by more than 50% of the readers—unless you specifically target device viewports in CSS, their experience won't be to see the entire definition on a single page anyway. Even desktop users will often have the page open on only half their screen.

Stepping back a bit, I don't think this conversation should block publication any longer—I still personally encourage you to consider breaking up that introduction section more, but that could always happen after an initial publication. Thanks for caring enough to read through such minute proposals!

[grtlr]

I agree with you that right now it is a little bit difficult to explore the different components of the covariance matrix (diagonal & off-diagonal elements) in an intuitive manner.

I had some discussion about this with Rebecca, one of our co-authors—maybe it would make sense to make the figure that we have stateful? You have already suggested a similar tweak for the posterior figure above. We, for example, could allow the user to click on the matrix to enable/disable different elements and constrain the dragging of the components respectively.

How would you feel about such an addition?

[ludwigschubert]

I feel like this would be an improvement on the status quo. To me, this still sounds more complicated than splitting the figure into two or more parts, but you may have insights into why that's not the case that I don't.

[theosanderson]

Amazing article.

At the moment the invisible handles work but the visible handles don't - so if you are too accurate with the mouse you are unable to drag (on my version of Chrome). With the instructions, and the hover animation, this is quite non-intuitive and threw me for a while. I don't know how hard it would be to solve.

[ludwigschubert]

@theosanderson can reproduce, thanks for taking the time to write an issue.

@RKehlbeck Could it be the invisible overlay needs to be on top of the visible handle? I just tried reordering them in dev tools and drag events worked as expected. (Moving both circle.handleInvisible tags to be the last SVG elements renders them on top.)

[ludwigschubert]

@RKehlbeck @theosanderson fixed in #48 — I just reordered nodes in your SVG drawing code. It's deploying atm. :-)