Interactivity warning / binder link / download link of notebooks

[maximlt]

Some documentation pages, that are built out of notebooks, require an active Python kernel to be fully interactive. For instance, anything that creates datashaded Bokeh plots would need Python running in the background to allow users to see that datashading happens every time they zoom in and out. Getting to a stage where the full interactivity would directly be available to users when they visit a site seems like it might one day be possible thanks to WASM, yet all of that is still pretty experimental and also comes with some disadvantages (e.g. increased page size). So for now we have to live with having no active Python kernel and static websites. To let the user know about this, a few solutions are available:

• a download link can be offered, which allows users to download the notebook and run it to get the full-interactivity. It assumes they have already set up their environment to run the notebook. Note that a download link is useful even if the users aren't interested in the full-interactivity, for instance if they just want to play around with the code, want that notebook as a starting point, etc.
• a Binder link can be offered. It has the same benefits as the download link, with the advantage of not forcing the user to install anything locally to run the notebook, and the disadvantage that Binder doesn't always work (it's a free service after all 🙃 )
• an interactivity warning box can be added to the page to indicate users that not all the interactivity will work in the page. This box can include download and binder links.

To illustrate these solutions, currently on this Panel page there's:

• a download link at the page start
• a Binder link in the right side bar
• an interactivity warning box in the right side bar, that offers a download link
• a download link at the page bottom (not shown in the screenshot)

As can be seen, these solutions can each be improved individually, but also should probably be rearranged/merged so that we don't end up with as many links as on the Panel page above.

For now I'm not making any suggestion, I'm just opening the discussion :) I would also suggest not focusing too much on the tooling to start the discussion (e.g. what nbsite does now, what pydata-sphinx-theme offers, etc.), instead I believe the discussion should focus first on the user experience, and then seek whether the available tools offer what has been decided, and if not see how hard it would be to implement it ourselves.

[maximlt]

Just to document another way to let users know the page isn't fully interactive.

[jbednar]

I agree that this is a major mess and should be dealt with. Note that most people won't understand what "static websites" are, so I don't think that warning is effective. And any warning that's at a specific point in the page, not visible when scrolled off, won't be very effective, because people click around rather than reading pages straight through.

What I think would be more effective is some sort of watermark actually covering the figure with a message about it only being an example and not fully interactive. Such a message would be ugly enough that we would want to get rid of it anywhere that it's not actually needed, which I think would be a good practice for us, as it would motivate us to remove such limitations wherever possible.

[droumis]

I agree and see three problems:

1. Some users expect full interactivity, don't see the warnings, and then get dissapointed by holoviz tools.
2. Some users see the warnings about needing to download for full interactively, and now have to go through the process of getting their environment set up, which adds cognitive and practical overhead.
3. The binder link is small and in a weird location under "on this page", so I think a lot of people miss it.

The ideal solution is of course to have them be fully interactive, which goes into an infrastructure and implementation discussion. I don't want to derail this conversation, but I think it would be worth discussing at some point soon.

For the near term, sticking with the current infrastructure, I think some sort of more prominent watermark or alert banner is an ugly but effective temporary idea. It doesn't have to cover the whole figure; maybe just the corner, or as a banner that can be closed by the user. Given that binder potentially solves the second problem (when it works) I think it should be merged and incorporated into the banner. Something like:

"Follow install instructions for full Python-backed interactivity, or open this page in Binder

If people don't like the plot watermark/banner idea, I think at least adding the binder link/text to the sticky bottom right alert box that says "...Right click to download and run locally..." is an improvement.

[maximlt]

Do we have any data on the share of users who are reading the docs on mobile? The right sidebar isn't displayed on mobile so people will miss any warning that is in there. This might make the banner a better option on mobile, if it can be closed and isn't too big. It would be nice to have a small mock up of how that would look like on desktop and mobile.

[droumis]

Since Jan 1, 2022, the fraction of mobile users on our websites:

hvplot is at ~11%
panel is at ~18%

all the other sites that we are tracking are somewhere within that range

[maximlt]

Interesting thanks! That is higher that I thought and definitely not negligible.